@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/runtime/telemetry/tracer.js

@@ -0,0 +1,210 @@
+import { SpanKind, SpanStatusCode } from './types.js';
+// ── ID generation ───────────────────────────────────────────────────────────────
+/** Generate a 128-bit trace ID (32-char lowercase hex). */
+function generateTraceId() {
+    return [
+        crypto.getRandomValues(new Uint8Array(16)),
+    ].map((bytes) => Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join(''))[0];
+}
+/** Generate a 64-bit span ID (16-char lowercase hex). */
+function generateSpanId() {
+    const bytes = crypto.getRandomValues(new Uint8Array(8));
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/** Check if a hex string is non-zero. */
+function isNonZeroHex(hex) {
+    return /[1-9a-f]/.test(hex);
+}
+// ── SpanImpl ──────────────────────────────────────────────────────────────────────
+class SpanImpl {
+    spanContext;
+    parentSpanId;
+    _ended = false;
+    _attributes = {};
+    _events = [];
+    _status = { code: SpanStatusCode.UNSET };
+    _startTimeMs;
+    _endTimeMs = 0;
+    _name;
+    _kind;
+    _scope;
+    _onEnd;
+    constructor(opts) {
+        this._name = opts.name;
+        this._kind = opts.kind;
+        this._scope = opts.scope;
+        this._startTimeMs = opts.startTimeMs ?? Date.now();
+        this._onEnd = opts.onEnd;
+        this.parentSpanId = opts.parentSpanId;
+        const spanId = generateSpanId();
+        this.spanContext = {
+            traceId: opts.traceId,
+            spanId,
+            isValid: isNonZeroHex(opts.traceId) && isNonZeroHex(spanId),
+        };
+    }
+    get ended() {
+        return this._ended;
+    }
+    setAttribute(key, value) {
+        if (this._ended)
+            return this;
+        this._attributes[key] = value;
+        return this;
+    }
+    setAttributes(attrs) {
+        if (this._ended)
+            return this;
+        Object.assign(this._attributes, attrs);
+        return this;
+    }
+    addEvent(name, attributes) {
+        if (this._ended)
+            return this;
+        this._events.push({ name, timestamp: Date.now(), attributes });
+        return this;
+    }
+    setStatus(status) {
+        if (this._ended)
+            return this;
+        // Only downgrade if current is UNSET; ERROR takes priority over OK
+        if (this._status.code === SpanStatusCode.UNSET || status.code === SpanStatusCode.ERROR) {
+            this._status = status;
+        }
+        return this;
+    }
+    recordException(error) {
+        if (this._ended)
+            return this;
+        this.addEvent('exception', {
+            'exception.type': error.name,
+            'exception.message': error.message,
+            'exception.stacktrace': error.stack ?? '',
+        });
+        this.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+        return this;
+    }
+    end(endTimeMs) {
+        if (this._ended)
+            return;
+        this._ended = true;
+        this._endTimeMs = endTimeMs ?? Date.now();
+        this._onEnd(this.toReadable());
+    }
+    toReadable() {
+        const endMs = this._endTimeMs > 0 ? this._endTimeMs : Date.now();
+        return Object.freeze({
+            name: this._name,
+            kind: this._kind,
+            spanContext: this.spanContext,
+            parentSpanId: this.parentSpanId,
+            startTimeMs: this._startTimeMs,
+            endTimeMs: endMs,
+            durationMs: endMs - this._startTimeMs,
+            attributes: { ...this._attributes },
+            events: [...this._events],
+            status: this._status,
+            instrumentationScope: this._scope,
+        });
+    }
+}
+// ── RuntimeTracer ──────────────────────────────────────────────────────────────
+/**
+ * RuntimeTracer — creates spans and routes completed spans to exporters.
+ *
+ * Usage:
+ * ```ts
+ * const span = tracer.startSpan('turn.lifecycle', { traceId, parentSpanId });
+ * span.setAttribute('turn.id', turnId);
+ * span.end();
+ * ```
+ */
+export class RuntimeTracer {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Start a new span.
+     *
+     * @param name - Human-readable span name.
+     * @param opts - Optional trace/parent context and kind.
+     */
+    startSpan(name, opts) {
+        if (!this.config.enabled) {
+            // Return a no-op span when tracing is disabled
+            return new NoopSpan();
+        }
+        const traceId = opts?.traceId ?? generateTraceId();
+        const span = new SpanImpl({
+            name,
+            kind: opts?.kind ?? SpanKind.INTERNAL,
+            traceId,
+            parentSpanId: opts?.parentSpanId,
+            startTimeMs: opts?.startTimeMs,
+            scope: this.config.scope,
+            onEnd: (readable) => this._export([readable]),
+        });
+        if (opts?.attributes) {
+            span.setAttributes(opts.attributes);
+        }
+        return span;
+    }
+    /**
+     * Flush all exporters. Call during graceful shutdown.
+     */
+    async flush() {
+        await Promise.allSettled(this.config.exporters.map((e) => e.flush()));
+    }
+    /**
+     * Shut down all exporters.
+     */
+    async shutdown() {
+        await Promise.allSettled(this.config.exporters.map((e) => e.shutdown()));
+    }
+    /** Fire-and-forget export to all registered exporters. */
+    _export(spans) {
+        for (const exporter of this.config.exporters) {
+            // Export is fire-and-forget; failures must not propagate
+            exporter.export(spans).catch(() => {
+                // Export failure — non-fatal, swallowed intentionally
+            });
+        }
+    }
+}
+// ── NoopSpan ───────────────────────────────────────────────────────────────────────
+/** No-op span returned when tracing is disabled. All operations are safe no-ops. */
+class NoopSpan {
+    spanContext = {
+        traceId: '00000000000000000000000000000000',
+        spanId: '0000000000000000',
+        isValid: false,
+    };
+    parentSpanId;
+    ended = false;
+    setAttribute(_key, _value) { return this; }
+    setAttributes(_attrs) { return this; }
+    addEvent(_name, _attributes) { return this; }
+    setStatus(_status) { return this; }
+    recordException(_error) { return this; }
+    end(_endTimeMs) { }
+    toReadable() {
+        return {
+            name: 'noop',
+            kind: SpanKind.INTERNAL,
+            spanContext: this.spanContext,
+            parentSpanId: undefined,
+            startTimeMs: 0,
+            endTimeMs: 0,
+            durationMs: 0,
+            attributes: {},
+            events: [],
+            status: { code: SpanStatusCode.UNSET },
+            instrumentationScope: 'noop',
+        };
+    }
+}

package/dist/_internal/platform/runtime/telemetry/types.d.ts

@@ -0,0 +1,167 @@
+/**
+ * OTel-compatible type definitions for the lightweight RuntimeTelemetry layer.
+ *
+ * Designed to be structurally compatible with the OpenTelemetry API without
+ * depending on the @opentelemetry/* packages. When the full SDK is introduced
+ * in a later tier, these types can be aliased to the SDK equivalents.
+ */
+/** Span status codes — mirrors OTel StatusCode. */
+export declare const SpanStatusCode: {
+    readonly UNSET: 0;
+    readonly OK: 1;
+    readonly ERROR: 2;
+};
+export type SpanStatusCode = (typeof SpanStatusCode)[keyof typeof SpanStatusCode];
+/** Span kind — mirrors OTel SpanKind. */
+export declare const SpanKind: {
+    readonly INTERNAL: 0;
+    readonly SERVER: 1;
+    readonly CLIENT: 2;
+    readonly PRODUCER: 3;
+    readonly CONSUMER: 4;
+};
+export type SpanKind = (typeof SpanKind)[keyof typeof SpanKind];
+/** Attribute value types compatible with OTel AttributeValue. */
+export type AttributeValue = string | number | boolean | string[] | number[] | boolean[];
+/** Key-value attribute bag. */
+export type SpanAttributes = Record<string, AttributeValue>;
+/** A timestamped annotation on a span (OTel SpanEvent). */
+export interface SpanEvent {
+    /** Event name. */
+    readonly name: string;
+    /** Epoch ms when the event occurred. */
+    readonly timestamp: number;
+    /** Optional attributes for this event. */
+    readonly attributes?: SpanAttributes;
+}
+/** Immutable span context — the W3C TraceContext identifiers. */
+export interface SpanContext {
+    /** 128-bit trace ID as 32-char hex string. */
+    readonly traceId: string;
+    /** 64-bit span ID as 16-char hex string. */
+    readonly spanId: string;
+    /** Whether this context is valid (both IDs are non-zero). */
+    readonly isValid: boolean;
+}
+/** Status of a span. */
+export interface SpanStatus {
+    readonly code: SpanStatusCode;
+    readonly message?: string;
+}
+/** A completed, immutable span record ready for export. */
+export interface ReadableSpan {
+    /** Span name (e.g. 'turn.lifecycle', 'tool.execute'). */
+    readonly name: string;
+    /** Span kind. */
+    readonly kind: SpanKind;
+    /** This span's context. */
+    readonly spanContext: SpanContext;
+    /** Parent span ID (undefined for root spans). */
+    readonly parentSpanId?: string;
+    /** Epoch ms when the span started. */
+    readonly startTimeMs: number;
+    /** Epoch ms when the span ended. */
+    readonly endTimeMs: number;
+    /** Duration in milliseconds. */
+    readonly durationMs: number;
+    /** Key-value attributes. */
+    readonly attributes: SpanAttributes;
+    /** Timestamped events on this span. */
+    readonly events: SpanEvent[];
+    /** Final status. */
+    readonly status: SpanStatus;
+    /** Instrumentation scope name (e.g. 'goodvibes-sdk/turn'). */
+    readonly instrumentationScope: string;
+}
+/** A mutable span under construction. */
+export interface Span {
+    /** Span context (traceId + spanId). */
+    readonly spanContext: SpanContext;
+    /** Parent span ID, if this is a child span. */
+    readonly parentSpanId?: string;
+    /** Whether the span has ended. */
+    readonly ended: boolean;
+    /** Set a single attribute. */
+    setAttribute(key: string, value: AttributeValue): this;
+    /** Set multiple attributes at once. */
+    setAttributes(attrs: SpanAttributes): this;
+    /** Add a timestamped event. */
+    addEvent(name: string, attributes?: SpanAttributes): this;
+    /** Set the final status. */
+    setStatus(status: SpanStatus): this;
+    /** Record an exception (shorthand for addEvent + setStatus ERROR). */
+    recordException(error: Error): this;
+    /**
+     * End the span, recording endTimeMs and durationMs.
+     * After calling end(), setAttribute/addEvent are no-ops.
+     */
+    end(endTimeMs?: number): void;
+    /** Return the immutable snapshot for export. */
+    toReadable(): ReadableSpan;
+}
+/** Label set for a metric observation. */
+export type MetricLabels = Record<string, string>;
+/** A counter — monotonically increasing value. */
+export interface Counter {
+    /** Increment by delta (default 1). Must be non-negative. */
+    add(delta?: number, labels?: MetricLabels): void;
+    /** Return current cumulative value for a label set. */
+    value(labels?: MetricLabels): number;
+}
+/** A histogram — distribution of observed values. */
+export interface Histogram {
+    /** Record an observation. */
+    record(value: number, labels?: MetricLabels): void;
+    /** Snapshot of recorded statistics for a label set. */
+    snapshot(labels?: MetricLabels): HistogramSnapshot;
+}
+/** Statistics snapshot for a histogram. */
+export interface HistogramSnapshot {
+    readonly count: number;
+    readonly sum: number;
+    readonly min: number;
+    readonly max: number;
+    /** Mean (sum / count), or 0 if count is 0. */
+    readonly mean: number;
+}
+/** A gauge — arbitrary point-in-time value. */
+export interface Gauge {
+    /** Set to an absolute value. */
+    set(value: number, labels?: MetricLabels): void;
+    /** Return current value for a label set. */
+    value(labels?: MetricLabels): number;
+}
+/** A span exporter — receives completed spans. */
+export interface SpanExporter {
+    /** Name for logging/identification. */
+    readonly name: string;
+    /** Export a batch of completed spans. Must not throw — swallow and log on failure. */
+    export(spans: ReadableSpan[]): Promise<void>;
+    /** Flush any buffered spans. */
+    flush(): Promise<void>;
+    /** Shut down the exporter gracefully. */
+    shutdown(): Promise<void>;
+}
+/** Configuration for the RuntimeTracer. */
+export interface TracerConfig {
+    /** Instrumentation scope (e.g. 'goodvibes-sdk'). */
+    readonly scope: string;
+    /** Exporters to send completed spans to. */
+    readonly exporters: SpanExporter[];
+    /**
+     * Whether to sample all spans (true) or disable tracing (false).
+     * Defaults to true when the otel-foundation feature flag is enabled.
+     */
+    readonly enabled: boolean;
+}
+/** Configuration for the RuntimeMeter. */
+export interface MeterConfig {
+    /** Instrumentation scope name (e.g. 'goodvibes-sdk'). */
+    readonly scope: string;
+}
+/** Combined telemetry provider configuration. */
+export interface TelemetryProviderConfig {
+    readonly tracer: TracerConfig;
+    readonly meter: MeterConfig;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/_internal/platform/runtime/telemetry/types.d.ts.map

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

package/dist/_internal/platform/runtime/telemetry/types.js

@@ -0,0 +1,22 @@
+/**
+ * OTel-compatible type definitions for the lightweight RuntimeTelemetry layer.
+ *
+ * Designed to be structurally compatible with the OpenTelemetry API without
+ * depending on the @opentelemetry/* packages. When the full SDK is introduced
+ * in a later tier, these types can be aliased to the SDK equivalents.
+ */
+// ── Span types ───────────────────────────────────────────────────────────────
+/** Span status codes — mirrors OTel StatusCode. */
+export const SpanStatusCode = {
+    UNSET: 0,
+    OK: 1,
+    ERROR: 2,
+};
+/** Span kind — mirrors OTel SpanKind. */
+export const SpanKind = {
+    INTERNAL: 0,
+    SERVER: 1,
+    CLIENT: 2,
+    PRODUCER: 3,
+    CONSUMER: 4,
+};

package/dist/_internal/platform/runtime/tools/adapter.d.ts

@@ -0,0 +1,60 @@
+import type { Tool } from '../../types/tools.js';
+/**
+ * Execution phases for the phased tool executor.
+ * Tools move through these phases in order; some tools may skip certain phases.
+ */
+export type ToolExecutionPhase = 'prehook' | 'executing' | 'posthook';
+/**
+ * A PhasedTool wraps a base Tool with metadata the phased executor uses
+ * to configure routing, phase skipping, timeouts, and cancellation.
+ *
+ * All existing Tool implementations remain valid; PhasedTool is purely additive.
+ * The `execute` contract is unchanged — callers that use the base ToolRegistry
+ * path continue working without modification.
+ */
+export interface PhasedTool extends Tool {
+    /**
+     * Tool category for permission classification and audit.
+     *
+     * - `read`     — reads data without side effects (files, network GETs)
+     * - `write`    — creates or modifies persistent state (files, database)
+     * - `execute`  — runs arbitrary code or shell commands
+     * - `delegate` — spawns sub-agents or recursive tool calls
+     * - `network`  — performs network I/O beyond simple reads
+     */
+    category: 'read' | 'write' | 'execute' | 'delegate' | 'network';
+    /**
+     * Phases to skip for this tool.
+     * For example, low-risk read tools may skip `prehook` and `posthook`
+     * to avoid unnecessary permission checks and audit overhead.
+     */
+    skipPhases?: ToolExecutionPhase[];
+    /**
+     * Per-phase timeout overrides in milliseconds.
+     * If not set, the phased executor's global defaults apply.
+     * Only meaningful for `executing` in most cases; hook phases are fast.
+     */
+    phaseTimeouts?: Partial<Record<ToolExecutionPhase, number>>;
+    /**
+     * Whether this tool supports cooperative cancellation via AbortSignal.
+     * If `true`, the phased executor passes `context.signal` and may abort
+     * the `executing` phase early. Non-cancellable tools ignore the signal.
+     */
+    cancellable: boolean;
+}
+/**
+ * Wraps a base Tool in a PhasedTool by merging the phased metadata.
+ * Use this in `createPhasedExecTool` / `createPhasedReadTool` factories
+ * to avoid duplicating the underlying tool's `definition` and `execute`.
+ *
+ * @param tool     - The existing Tool implementation to wrap.
+ * @param options  - Phased execution metadata to attach.
+ * @returns A PhasedTool that delegates execution to the original tool.
+ */
+export declare function asPhasedTool(tool: Tool, options: {
+    category: PhasedTool['category'];
+    cancellable: boolean;
+    skipPhases?: ToolExecutionPhase[];
+    phaseTimeouts?: Partial<Record<ToolExecutionPhase, number>>;
+}): PhasedTool;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/_internal/platform/runtime/tools/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/tools/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,sBAAsB,CAAC;AAE7D;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,WAAW,GACX,UAAU,CAAC;AAEf;;;;;;;GAOG;AACH,MAAM,WAAW,UAAW,SAAQ,IAAI;IACtC;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;IAEhE;;;;OAIG;IACH,UAAU,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAElC;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,CAAC;IAE5D;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,EACV,OAAO,EAAE;IACP,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAClC,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7D,GACA,UAAU,CASZ"}

package/dist/_internal/platform/runtime/tools/adapter.js

@@ -0,0 +1,19 @@
+/**
+ * Wraps a base Tool in a PhasedTool by merging the phased metadata.
+ * Use this in `createPhasedExecTool` / `createPhasedReadTool` factories
+ * to avoid duplicating the underlying tool's `definition` and `execute`.
+ *
+ * @param tool     - The existing Tool implementation to wrap.
+ * @param options  - Phased execution metadata to attach.
+ * @returns A PhasedTool that delegates execution to the original tool.
+ */
+export function asPhasedTool(tool, options) {
+    return {
+        definition: tool.definition,
+        execute: tool.execute.bind(tool),
+        category: options.category,
+        cancellable: options.cancellable,
+        skipPhases: options.skipPhases,
+        phaseTimeouts: options.phaseTimeouts,
+    };
+}

package/dist/_internal/platform/runtime/tools/contract-verifier.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Tool Contract Verifier — registration-time contract checks for all registered tools.
+ *
+ * Validates five contract dimensions for every tool:
+ * 1. Schema validity
+ * 2. Timeout/cancellation semantics
+ * 3. Permission class mapping
+ * 4. Output policy compatibility
+ * 5. Idempotency declaration for side-effecting tools
+ *
+ * Invalid tools fail closed: a tool with contract violations is rejected at
+ * registration time with actionable diagnostics surfaced to the caller.
+ */
+import type { Tool } from '../../types/tools.js';
+/** Severity of a single contract violation. */
+export type ContractViolationSeverity = 'error' | 'warn';
+/** A single contract check that failed or produced a warning. */
+export interface ContractViolation {
+    /** Which of the 5 contract dimensions this belongs to. */
+    readonly dimension: 'schema' | 'timeout-cancellation' | 'permission-class' | 'output-policy' | 'idempotency';
+    /** Severity of the violation. */
+    readonly severity: ContractViolationSeverity;
+    /** Human-readable explanation of what is wrong. */
+    readonly message: string;
+    /** Optional hint for how to fix the violation. */
+    readonly hint?: string;
+}
+/** Full contract verification result for a single tool. */
+export interface ContractVerificationResult {
+    /** Tool name. */
+    readonly toolName: string;
+    /** Whether the tool passed all required (error-level) checks. */
+    readonly passed: boolean;
+    /** All violations found. May include warnings even if passed. */
+    readonly violations: readonly ContractViolation[];
+    /** Unix timestamp (ms) when this result was produced. */
+    readonly verifiedAt: number;
+    /** Whether this tool was verified as a PhasedTool (has extended metadata). */
+    readonly isPhasedTool: boolean;
+}
+/**
+ * Options controlling which contract checks run and how strictly.
+ */
+export interface ContractVerifierOptions {
+    /**
+     * Whether to treat missing idempotency declarations on side-effecting tools
+     * as errors (true, default) or warnings (false).
+     *
+     * Set to false while tightening tool metadata requirements incrementally.
+     */
+    strictIdempotency?: boolean;
+    /**
+     * Whether to treat missing permission class metadata as errors (true) or
+     * warnings (false, default for tool definitions that omit that metadata).
+     */
+    strictPermissionClass?: boolean;
+}
+/**
+ * ToolContractVerifier — runs all 5 contract checks on a single tool.
+ *
+ * Usage:
+ * ```ts
+ * const verifier = new ToolContractVerifier();
+ * const result = verifier.verify(myTool);
+ * if (!result.passed) {
+ *   for (const v of result.violations.filter(v => v.severity === 'error')) {
+ *     throw new Error(v.message);
+ *   }
+ * }
+ * ```
+ */
+export declare class ToolContractVerifier {
+    private readonly _opts;
+    constructor(opts?: ContractVerifierOptions);
+    /**
+     * Verify a single tool against all 5 contract dimensions.
+     *
+     * @param tool - The tool to verify.
+     * @returns A ContractVerificationResult with all violations and a pass/fail flag.
+     */
+    verify(tool: Tool): ContractVerificationResult;
+    /**
+     * Verify multiple tools at once.
+     *
+     * @param tools - Array of tools to verify.
+     * @returns Map of tool name to verification result.
+     */
+    verifyAll(tools: readonly Tool[]): Map<string, ContractVerificationResult>;
+    /**
+     * Format a verification result as a human-readable diagnostic string.
+     * Suitable for printing to the console or a diagnostics panel.
+     *
+     * @param result - The result to format.
+     * @returns Multi-line formatted diagnostic string.
+     */
+    static formatResult(result: ContractVerificationResult): string;
+    /**
+     * Format a map of results (from verifyAll) as a human-readable summary.
+     *
+     * @param results - Map of tool name to verification result.
+     * @returns Multi-line formatted diagnostic string.
+     */
+    static formatAllResults(results: Map<string, ContractVerificationResult>): string;
+}
+//# sourceMappingURL=contract-verifier.d.ts.map

package/dist/_internal/platform/runtime/tools/contract-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-verifier.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/tools/contract-verifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAkB,MAAM,sBAAsB,CAAC;AA+BjE,+CAA+C;AAC/C,MAAM,MAAM,yBAAyB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEzD,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EACd,QAAQ,GACR,sBAAsB,GACtB,kBAAkB,GAClB,eAAe,GACf,aAAa,CAAC;IAClB,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAC;IAC7C,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,2DAA2D;AAC3D,MAAM,WAAW,0BAA0B;IACzC,iBAAiB;IACjB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAClD,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAwOD;;;;;;;;;;;;;GAaG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;gBAE9C,IAAI,GAAE,uBAA4B;IAO9C;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,0BAA0B;IAuB9C;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAQ1E;;;;;;OAMG;IACH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,0BAA0B,GAAG,MAAM;IAqB/D;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,0BAA0B,CAAC,GAAG,MAAM;CAoBlF"}