@predicatelabs/sdk 0.99.9

package/dist/tracing/tracer-factory.js

@@ -0,0 +1,375 @@
+"use strict";
+/**
+ * Tracer Factory with Automatic Tier Detection
+ *
+ * Provides convenient factory function for creating tracers with cloud upload support
+ *
+ * PRODUCTION HARDENING:
+ * - Recovers orphaned traces from previous crashes on SDK init (Risk #3)
+ * - Passes runId to CloudTraceSink for persistent cache naming (Risk #1)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SENTIENCE_API_URL = void 0;
+exports.createTracer = createTracer;
+exports.createLocalTracer = createLocalTracer;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const https = __importStar(require("https"));
+const http = __importStar(require("http"));
+const url_1 = require("url");
+const crypto_1 = require("crypto");
+const tracer_1 = require("./tracer");
+const cloud_sink_1 = require("./cloud-sink");
+const jsonl_sink_1 = require("./jsonl-sink");
+/**
+ * Helper to emit run_start event with available metadata
+ */
+function emitRunStart(tracer, agentType, llmModel, goal, startUrl) {
+    try {
+        const config = {};
+        if (goal) {
+            config.goal = goal;
+        }
+        if (startUrl) {
+            config.start_url = startUrl;
+        }
+        tracer.emitRunStart(agentType || 'SentienceAgent', llmModel, Object.keys(config).length > 0 ? config : undefined);
+    }
+    catch {
+        // Tracing must be non-fatal
+    }
+}
+/**
+ * Sentience API base URL (constant)
+ */
+exports.SENTIENCE_API_URL = 'https://api.sentienceapi.com';
+/**
+ * Get persistent cache directory for traces
+ */
+function getPersistentCacheDir() {
+    const homeDir = os.homedir();
+    return path.join(homeDir, '.sentience', 'traces', 'pending');
+}
+/**
+ * Recover orphaned traces from previous crashes
+ * PRODUCTION FIX: Risk #3 - Upload traces from crashed sessions
+ *
+ * Note: Silently skips in test environments to avoid test noise
+ */
+async function recoverOrphanedTraces(apiKey, apiUrl = exports.SENTIENCE_API_URL) {
+    // Skip orphan recovery in test environments (CI, Jest, etc.)
+    // This prevents test failures from orphan recovery attempts
+    const isTestEnv = process.env.CI === 'true' ||
+        process.env.NODE_ENV === 'test' ||
+        process.env.JEST_WORKER_ID !== undefined ||
+        (typeof global !== 'undefined' && global.__JEST__);
+    if (isTestEnv) {
+        return;
+    }
+    const cacheDir = getPersistentCacheDir();
+    if (!fs.existsSync(cacheDir)) {
+        return;
+    }
+    let orphanedFiles;
+    try {
+        orphanedFiles = fs.readdirSync(cacheDir).filter(f => f.endsWith('.jsonl'));
+    }
+    catch (error) {
+        // Silently fail if directory read fails (permissions, etc.)
+        return;
+    }
+    if (orphanedFiles.length === 0) {
+        return;
+    }
+    console.log(`⚠️  [Sentience] Found ${orphanedFiles.length} un-uploaded trace(s) from previous run(s)`);
+    console.log('   Attempting to upload now...');
+    for (const file of orphanedFiles) {
+        const filePath = path.join(cacheDir, file);
+        const runId = path.basename(file, '.jsonl');
+        try {
+            // Request upload URL for this orphaned trace
+            // Use a shorter timeout for orphan recovery to avoid blocking
+            const response = await Promise.race([
+                httpPost(`${apiUrl}/v1/traces/init`, { run_id: runId }, { Authorization: `Bearer ${apiKey}` }),
+                new Promise(resolve => setTimeout(() => resolve({ status: 500, data: {} }), 5000)),
+            ]);
+            if (response.status === 200 && response.data.upload_url) {
+                // Create a temporary CloudTraceSink to upload this orphaned trace
+                const sink = new cloud_sink_1.CloudTraceSink(response.data.upload_url, runId);
+                await sink.close(); // This will upload the existing file
+                console.log(`✅ [Sentience] Uploaded orphaned trace: ${runId}`);
+            }
+            else if (response.status === 409) {
+                // HTTP 409 means trace already exists (already uploaded)
+                // Treat as success and delete local file
+                console.log(`✅ [Sentience] Trace ${runId} already exists in cloud (skipping re-upload)`);
+                try {
+                    fs.unlinkSync(filePath);
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+            // Silently skip other failures - don't log errors for orphan recovery
+            // These are expected in many scenarios (network issues, invalid API keys, etc.)
+        }
+        catch (error) {
+            // Silently skip failures - don't log errors for orphan recovery
+            // These are expected in many scenarios (network issues, invalid API keys, etc.)
+        }
+    }
+}
+/**
+ * Make HTTP/HTTPS POST request using built-in Node modules
+ */
+function httpPost(url, data, headers) {
+    return new Promise((resolve, reject) => {
+        const urlObj = new url_1.URL(url);
+        const protocol = urlObj.protocol === 'https:' ? https : http;
+        const body = JSON.stringify(data);
+        const options = {
+            hostname: urlObj.hostname,
+            port: urlObj.port || (urlObj.protocol === 'https:' ? 443 : 80),
+            path: urlObj.pathname + urlObj.search,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Content-Length': Buffer.byteLength(body),
+                ...headers,
+            },
+            timeout: 10000, // 10 second timeout
+        };
+        const req = protocol.request(options, res => {
+            let responseBody = '';
+            res.on('data', chunk => {
+                responseBody += chunk;
+            });
+            res.on('end', () => {
+                try {
+                    const parsed = responseBody ? JSON.parse(responseBody) : {};
+                    resolve({ status: res.statusCode || 500, data: parsed });
+                }
+                catch (error) {
+                    resolve({ status: res.statusCode || 500, data: {} });
+                }
+            });
+        });
+        req.on('error', error => {
+            reject(error);
+        });
+        req.on('timeout', () => {
+            req.destroy();
+            reject(new Error('Request timeout'));
+        });
+        req.write(body);
+        req.end();
+    });
+}
+/**
+ * Create tracer with automatic tier detection
+ *
+ * Tier Detection:
+ * - If apiKey is provided AND uploadTrace is true: Try to initialize CloudTraceSink (Pro/Enterprise)
+ * - If cloud init fails, no apiKey, or uploadTrace is false: Fall back to JsonlTraceSink (Free tier)
+ *
+ * @param options - Configuration options
+ * @param options.apiKey - Sentience API key (e.g., "sk_pro_xxxxx")
+ * @param options.runId - Unique identifier for this agent run (generates UUID if not provided)
+ * @param options.apiUrl - Sentience API base URL (default: https://api.sentienceapi.com)
+ * @param options.logger - Optional logger instance for logging file sizes and errors
+ * @param options.uploadTrace - Enable cloud trace upload (default: true for backward compatibility)
+ * @param options.goal - User's goal/objective for this trace run. This will be displayed as the trace name in the frontend. Should be descriptive and action-oriented. Example: "Add wireless headphones to cart on Amazon"
+ * @param options.agentType - Type of agent running (e.g., "SentienceAgent", "CustomAgent")
+ * @param options.llmModel - LLM model used (e.g., "gpt-4-turbo", "claude-3-5-sonnet")
+ * @param options.startUrl - Starting URL of the agent run (e.g., "https://amazon.com")
+ * @param options.screenshotProcessor - Optional function to process screenshots before upload. Takes base64 string, returns processed base64 string. Useful for PII redaction or custom image processing.
+ * @param options.autoEmitRunStart - If true (default), automatically emit run_start event with provided metadata. This ensures traces have complete structure for Studio visualization.
+ * @returns Tracer configured with appropriate sink
+ *
+ * @example
+ * ```typescript
+ * // Pro tier user with goal and metadata
+ * const tracer = await createTracer({
+ *   apiKey: "sk_pro_xyz",
+ *   runId: "demo",
+ *   goal: "Add headphones to cart",
+ *   agentType: "SentienceAgent",
+ *   llmModel: "gpt-4-turbo",
+ *   startUrl: "https://amazon.com",
+ *   uploadTrace: true
+ * });
+ * // Returns: Tracer with CloudTraceSink
+ * // run_start event is automatically emitted
+ *
+ * // With screenshot processor for PII redaction
+ * const redactPII = (screenshot: string): string => {
+ *   // Your custom redaction logic
+ *   return redactedScreenshot;
+ * };
+ * const tracer = await createTracer({
+ *   apiKey: "sk_pro_xyz",
+ *   screenshotProcessor: redactPII
+ * });
+ * // Screenshots will be processed before upload
+ *
+ * // Pro tier user with local-only tracing
+ * const tracer = await createTracer({ apiKey: "sk_pro_xyz", runId: "demo", uploadTrace: false });
+ * // Returns: Tracer with JsonlTraceSink (local-only)
+ *
+ * // Disable auto-emit for manual control
+ * const tracer = await createTracer({ runId: "demo", autoEmitRunStart: false });
+ * tracer.emitRunStart("MyAgent", "gpt-4o"); // Manual emit
+ *
+ * // Free tier user
+ * const tracer = await createTracer({ runId: "demo" });
+ * // Returns: Tracer with JsonlTraceSink (local-only)
+ *
+ * // Use with agent
+ * const agent = new SentienceAgent(browser, llm, 50, true, tracer);
+ * await agent.act("Click search");
+ * await tracer.close(); // Uploads to cloud if uploadTrace: true and Pro tier
+ * ```
+ */
+async function createTracer(options) {
+    const runId = options.runId || (0, crypto_1.randomUUID)();
+    const apiUrl = options.apiUrl || exports.SENTIENCE_API_URL;
+    // Default uploadTrace to true for backward compatibility
+    const uploadTrace = options.uploadTrace !== false;
+    // PRODUCTION FIX: Recover orphaned traces from previous crashes
+    // Note: This is skipped in test environments (see recoverOrphanedTraces function)
+    // Run in background to avoid blocking tracer creation
+    // Only recover if uploadTrace is enabled
+    if (options.apiKey && uploadTrace) {
+        // Don't await - run in background to avoid blocking
+        recoverOrphanedTraces(options.apiKey, apiUrl).catch(() => {
+            // Silently fail - orphan recovery should not block tracer creation
+        });
+    }
+    // 1. Try to initialize Cloud Sink (Pro/Enterprise tier)
+    // Only attempt cloud init if uploadTrace is enabled
+    if (options.apiKey && uploadTrace) {
+        try {
+            // Build metadata object for trace initialization
+            // Only include non-empty fields to avoid sending empty strings
+            const metadata = {};
+            if (options.goal && options.goal.trim()) {
+                metadata.goal = options.goal.trim();
+            }
+            if (options.agentType && options.agentType.trim()) {
+                metadata.agent_type = options.agentType.trim();
+            }
+            if (options.llmModel && options.llmModel.trim()) {
+                metadata.llm_model = options.llmModel.trim();
+            }
+            if (options.startUrl && options.startUrl.trim()) {
+                metadata.start_url = options.startUrl.trim();
+            }
+            // Build request payload
+            const payload = { run_id: runId };
+            if (Object.keys(metadata).length > 0) {
+                payload.metadata = metadata;
+            }
+            // Request pre-signed upload URL from backend
+            const response = await httpPost(`${apiUrl}/v1/traces/init`, payload, {
+                Authorization: `Bearer ${options.apiKey}`,
+            });
+            if (response.status === 200 && response.data.upload_url) {
+                const uploadUrl = response.data.upload_url;
+                console.log('☁️  [Sentience] Cloud tracing enabled (Pro tier)');
+                // PRODUCTION FIX: Pass runId for persistent cache naming
+                const tracer = new tracer_1.Tracer(runId, new cloud_sink_1.CloudTraceSink(uploadUrl, runId, options.apiKey, apiUrl, options.logger), options.screenshotProcessor);
+                // Auto-emit run_start for complete trace structure
+                if (options.autoEmitRunStart !== false) {
+                    emitRunStart(tracer, options.agentType, options.llmModel, options.goal, options.startUrl);
+                }
+                return tracer;
+            }
+            else if (response.status === 403) {
+                console.log('⚠️  [Sentience] Cloud tracing requires Pro tier');
+                console.log('   Falling back to local-only tracing');
+            }
+            else {
+                console.log(`⚠️  [Sentience] Cloud init failed: HTTP ${response.status}`);
+                console.log('   Falling back to local-only tracing');
+            }
+        }
+        catch (error) {
+            if (error.message?.includes('timeout')) {
+                console.log('⚠️  [Sentience] Cloud init timeout');
+            }
+            else if (error.code === 'ECONNREFUSED' || error.message?.includes('connect')) {
+                console.log('⚠️  [Sentience] Cloud init connection error');
+            }
+            else {
+                console.log(`⚠️  [Sentience] Cloud init error: ${error.message}`);
+            }
+            console.log('   Falling back to local-only tracing');
+        }
+    }
+    // 2. Fallback to Local Sink (Free tier / Offline mode)
+    const tracesDir = path.join(process.cwd(), 'traces');
+    // Create traces directory if it doesn't exist
+    if (!fs.existsSync(tracesDir)) {
+        fs.mkdirSync(tracesDir, { recursive: true });
+    }
+    const localPath = path.join(tracesDir, `${runId}.jsonl`);
+    console.log(`💾 [Sentience] Local tracing: ${localPath}`);
+    const tracer = new tracer_1.Tracer(runId, new jsonl_sink_1.JsonlTraceSink(localPath), options.screenshotProcessor);
+    // Auto-emit run_start for complete trace structure
+    if (options.autoEmitRunStart !== false) {
+        emitRunStart(tracer, options.agentType, options.llmModel, options.goal, options.startUrl);
+    }
+    return tracer;
+}
+/**
+ * Synchronous version of createTracer for non-async contexts
+ * Always returns local JsonlTraceSink (no cloud upload)
+ *
+ * @param runId - Unique identifier for this agent run (generates UUID if not provided)
+ * @returns Tracer with JsonlTraceSink
+ */
+function createLocalTracer(runId) {
+    const traceRunId = runId || (0, crypto_1.randomUUID)();
+    const tracesDir = path.join(process.cwd(), 'traces');
+    if (!fs.existsSync(tracesDir)) {
+        fs.mkdirSync(tracesDir, { recursive: true });
+    }
+    const localPath = path.join(tracesDir, `${traceRunId}.jsonl`);
+    console.log(`💾 [Sentience] Local tracing: ${localPath}`);
+    return new tracer_1.Tracer(traceRunId, new jsonl_sink_1.JsonlTraceSink(localPath));
+}
+//# sourceMappingURL=tracer-factory.js.map

package/dist/tracing/tracer-factory.js.map

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

package/dist/tracing/tracer.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Tracer Class
+ *
+ * High-level API for emitting trace events with automatic sequencing and timestamps
+ */
+import { TraceSink } from './sink';
+import { TraceEventData } from './types';
+/**
+ * Tracer provides a high-level API for recording agent execution traces
+ */
+export declare class Tracer {
+    private runId;
+    private sink;
+    private seq;
+    private screenshotProcessor?;
+    private totalSteps;
+    private totalEvents;
+    private startedAt;
+    private endedAt;
+    private finalStatus;
+    private stepSuccesses;
+    private stepFailures;
+    private hasErrors;
+    /**
+     * Create a new Tracer
+     * @param runId - Unique run identifier (UUID)
+     * @param sink - TraceSink implementation (e.g., JsonlTraceSink)
+     * @param screenshotProcessor - Optional function to process screenshots before emission.
+     *                             Takes base64 string, returns processed base64 string.
+     *                             Useful for PII redaction or custom image processing.
+     *
+     * @example
+     * // Basic usage
+     * const sink = new JsonlTraceSink('trace.jsonl');
+     * const tracer = new Tracer('run-123', sink);
+     *
+     * @example
+     * // With screenshot processor for PII redaction
+     * const redactPII = (screenshot: string): string => {
+     *   // Your custom redaction logic
+     *   return redactedScreenshot;
+     * };
+     * const tracer = new Tracer('run-123', sink, redactPII);
+     */
+    constructor(runId: string, sink: TraceSink, screenshotProcessor?: (screenshot: string) => string);
+    /**
+     * Emit a trace event
+     * @param eventType - Type of event (e.g., 'run_start', 'snapshot')
+     * @param data - Event-specific payload
+     * @param stepId - Optional step UUID
+     */
+    emit(eventType: string, data: TraceEventData, stepId?: string): void;
+    /**
+     * Emit run_start event
+     * @param agent - Agent type (e.g., 'SentienceAgent')
+     * @param llmModel - Optional LLM model name
+     * @param config - Optional configuration
+     */
+    emitRunStart(agent: string, llmModel?: string, config?: Record<string, any>): void;
+    /**
+     * Emit step_start event
+     * @param stepId - Step UUID
+     * @param stepIndex - Step number (1-indexed)
+     * @param goal - Goal description
+     * @param attempt - Retry attempt number (0 = first try)
+     * @param preUrl - Optional URL before step execution
+     */
+    emitStepStart(stepId: string, stepIndex: number, goal: string, attempt?: number, preUrl?: string): void;
+    /**
+     * Emit run_end event
+     * @param steps - Total number of steps executed
+     * @param status - Optional final status ("success", "failure", "partial", "unknown")
+     *                 If not provided, infers from tracked outcomes or uses this.finalStatus
+     */
+    emitRunEnd(steps: number, status?: string): void;
+    /**
+     * Emit error event
+     * @param stepId - Step UUID where error occurred
+     * @param error - Error message
+     * @param attempt - Retry attempt number
+     */
+    emitError(stepId: string, error: string, attempt?: number): void;
+    /**
+     * Emit snapshot event with screenshot for Studio visualization.
+     *
+     * This method builds and emits a 'snapshot' trace event that includes:
+     * - Page URL and element data
+     * - Screenshot (if present in snapshot)
+     * - Step correlation info
+     *
+     * Use this when you want screenshots to appear in the Sentience Studio timeline.
+     *
+     * @param snapshot - Snapshot object (must have 'screenshot' property for images)
+     * @param stepId - Step UUID (for correlating snapshot with a step)
+     * @param stepIndex - Step index (0-based) for Studio timeline ordering
+     * @param screenshotFormat - Format of screenshot ("jpeg" or "png", default: "jpeg")
+     *
+     * @example
+     * // After taking a snapshot with AgentRuntime
+     * const snapshot = await runtime.snapshot();
+     * tracer.emitSnapshot(snapshot, runtime.getStepId(), runtime.getStepIndex());
+     *
+     * // Or use auto-emit (default in AgentRuntime.snapshot())
+     * const snapshot = await runtime.snapshot();  // Auto-emits snapshot event
+     */
+    emitSnapshot(snapshot: any, stepId?: string, stepIndex?: number, screenshotFormat?: string): void;
+    /**
+     * Automatically infer finalStatus from tracked step outcomes if not explicitly set.
+     * This is called automatically in close() if finalStatus is still "unknown".
+     */
+    private _inferFinalStatus;
+    /**
+     * Close the underlying sink (flush buffered data)
+     * @param blocking - If false, upload happens in background (default: true). Only applies to CloudTraceSink.
+     */
+    close(blocking?: boolean): Promise<void>;
+    /**
+     * Get run ID
+     */
+    getRunId(): string;
+    /**
+     * Get current sequence number
+     */
+    getSeq(): number;
+    /**
+     * Get sink type (for debugging)
+     */
+    getSinkType(): string;
+    /**
+     * Set the final status of the trace run
+     * @param status - Final status ("success", "failure", "partial", "unknown")
+     */
+    setFinalStatus(status: string): void;
+    /**
+     * Get execution statistics for trace completion
+     * @returns Dictionary with stats fields for /v1/traces/complete
+     */
+    getStats(): Record<string, any>;
+}
+//# sourceMappingURL=tracer.d.ts.map

package/dist/tracing/tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/tracing/tracer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EAAc,cAAc,EAAE,MAAM,SAAS,CAAC;AAErD;;GAEG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,IAAI,CAAY;IACxB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,mBAAmB,CAAC,CAAiC;IAG7D,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,WAAW,CAAqB;IAExC,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,SAAS,CAAkB;IAEnC;;;;;;;;;;;;;;;;;;;;OAoBG;gBAED,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,EACf,mBAAmB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM;IAQtD;;;;;OAKG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IA2CpE;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAWlF;;;;;;;OAOG;IACH,aAAa,CACX,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,MAAU,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAoBP;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IA2BhD;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,MAAU,GAAG,IAAI;IAInE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,YAAY,CACV,QAAQ,EAAE,GAAG,EACb,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,EAClB,gBAAgB,GAAE,MAAe,GAChC,IAAI;IA2DP;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAqBzB;;;OAGG;IACG,KAAK,CAAC,QAAQ,GAAE,OAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBpD;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;OAEG;IACH,WAAW,IAAI,MAAM;IAIrB;;;OAGG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IASpC;;;OAGG;IACH,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CAehC"}