@runcore-sh/runcore 0.1.2

package/dist/tracing/instrument.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Instrumentation helpers for wrapping Core operations with OTel spans.
+ *
+ * Provides typed wrappers for the key operation categories:
+ * - Agent execution (spawn, lifecycle)
+ * - External API calls (Linear, Google, OpenRouter)
+ * - File operations (ingest, read, write)
+ * - HTTP request handling
+ *
+ * Each wrapper creates an OTel span, records relevant attributes,
+ * and properly handles errors and status codes.
+ */
+import { type Span, SpanKind } from "@opentelemetry/api";
+/**
+ * Wrap an async operation in an OTel span.
+ * Automatically records errors and sets span status.
+ */
+export declare function withSpan<T>(name: string, fn: (span: Span) => Promise<T>, opts?: {
+    kind?: SpanKind;
+    attributes?: Record<string, string | number | boolean>;
+}): Promise<T>;
+/**
+ * Wrap a synchronous operation in an OTel span.
+ */
+export declare function withSpanSync<T>(name: string, fn: (span: Span) => T, opts?: {
+    kind?: SpanKind;
+    attributes?: Record<string, string | number | boolean>;
+}): T;
+/** Wrap an agent spawn operation. */
+export declare function traceAgentSpawn<T>(taskId: string, label: string, origin: string, fn: (span: Span) => Promise<T>): Promise<T>;
+/** Wrap agent execution (the full lifecycle of a single agent run). */
+export declare function traceAgentExecution<T>(taskId: string, label: string, fn: (span: Span) => Promise<T>): Promise<T>;
+/** Wrap an external API call (Linear, Google, OpenRouter, etc.). */
+export declare function traceApiCall<T>(service: string, operation: string, fn: (span: Span) => Promise<T>): Promise<T>;
+/** Wrap a file operation (read, write, ingest). */
+export declare function traceFileOp<T>(operation: string, path: string, fn: (span: Span) => Promise<T>): Promise<T>;
+/** Wrap an HTTP request handler. */
+export declare function traceHttpRequest<T>(method: string, route: string, fn: (span: Span) => Promise<T>): Promise<T>;
+//# sourceMappingURL=instrument.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instrument.d.ts","sourceRoot":"","sources":["../../src/tracing/instrument.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,KAAK,IAAI,EAET,QAAQ,EAGT,MAAM,oBAAoB,CAAC;AAQ5B;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9B,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACxD,GACA,OAAO,CAAC,CAAC,CAAC,CAgCZ;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EACrB,IAAI,CAAC,EAAE;IACL,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACxD,GACA,CAAC,CA4BH;AAMD,qCAAqC;AACrC,wBAAsB,eAAe,CAAC,CAAC,EACrC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CASZ;AAED,uEAAuE;AACvE,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CAQZ;AAMD,oEAAoE;AACpE,wBAAsB,YAAY,CAAC,CAAC,EAClC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CAQZ;AAMD,mDAAmD;AACnD,wBAAsB,WAAW,CAAC,CAAC,EACjC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CAOZ;AAMD,oCAAoC;AACpC,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CAQZ"}

package/dist/tracing/instrument.js

@@ -0,0 +1,145 @@
+/**
+ * Instrumentation helpers for wrapping Core operations with OTel spans.
+ *
+ * Provides typed wrappers for the key operation categories:
+ * - Agent execution (spawn, lifecycle)
+ * - External API calls (Linear, Google, OpenRouter)
+ * - File operations (ingest, read, write)
+ * - HTTP request handling
+ *
+ * Each wrapper creates an OTel span, records relevant attributes,
+ * and properly handles errors and status codes.
+ */
+import { SpanStatusCode, SpanKind, } from "@opentelemetry/api";
+import { getTracer } from "./init.js";
+import { getCorrelationId } from "./correlation.js";
+// ---------------------------------------------------------------------------
+// Generic span wrapper
+// ---------------------------------------------------------------------------
+/**
+ * Wrap an async operation in an OTel span.
+ * Automatically records errors and sets span status.
+ */
+export async function withSpan(name, fn, opts) {
+    const tracer = getTracer();
+    return tracer.startActiveSpan(name, {
+        kind: opts?.kind ?? SpanKind.INTERNAL,
+        attributes: {
+            ...opts?.attributes,
+            ...(getCorrelationId()
+                ? { "dash.correlation_id": getCorrelationId() }
+                : {}),
+        },
+    }, async (span) => {
+        try {
+            const result = await fn(span);
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (err) {
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: err instanceof Error ? err.message : String(err),
+            });
+            span.recordException(err instanceof Error ? err : new Error(String(err)));
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/**
+ * Wrap a synchronous operation in an OTel span.
+ */
+export function withSpanSync(name, fn, opts) {
+    const tracer = getTracer();
+    const span = tracer.startSpan(name, {
+        kind: opts?.kind ?? SpanKind.INTERNAL,
+        attributes: {
+            ...opts?.attributes,
+            ...(getCorrelationId()
+                ? { "dash.correlation_id": getCorrelationId() }
+                : {}),
+        },
+    });
+    try {
+        const result = fn(span);
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+    }
+    catch (err) {
+        span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: err instanceof Error ? err.message : String(err),
+        });
+        span.recordException(err instanceof Error ? err : new Error(String(err)));
+        throw err;
+    }
+    finally {
+        span.end();
+    }
+}
+// ---------------------------------------------------------------------------
+// Agent instrumentation
+// ---------------------------------------------------------------------------
+/** Wrap an agent spawn operation. */
+export async function traceAgentSpawn(taskId, label, origin, fn) {
+    return withSpan(`agent.spawn`, fn, {
+        kind: SpanKind.PRODUCER,
+        attributes: {
+            "agent.task_id": taskId,
+            "agent.label": label,
+            "agent.origin": origin,
+        },
+    });
+}
+/** Wrap agent execution (the full lifecycle of a single agent run). */
+export async function traceAgentExecution(taskId, label, fn) {
+    return withSpan(`agent.execute`, fn, {
+        kind: SpanKind.INTERNAL,
+        attributes: {
+            "agent.task_id": taskId,
+            "agent.label": label,
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// API call instrumentation
+// ---------------------------------------------------------------------------
+/** Wrap an external API call (Linear, Google, OpenRouter, etc.). */
+export async function traceApiCall(service, operation, fn) {
+    return withSpan(`${service}.${operation}`, fn, {
+        kind: SpanKind.CLIENT,
+        attributes: {
+            "rpc.service": service,
+            "rpc.method": operation,
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// File operation instrumentation
+// ---------------------------------------------------------------------------
+/** Wrap a file operation (read, write, ingest). */
+export async function traceFileOp(operation, path, fn) {
+    return withSpan(`file.${operation}`, fn, {
+        attributes: {
+            "file.operation": operation,
+            "file.path": path,
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// HTTP instrumentation
+// ---------------------------------------------------------------------------
+/** Wrap an HTTP request handler. */
+export async function traceHttpRequest(method, route, fn) {
+    return withSpan(`HTTP ${method} ${route}`, fn, {
+        kind: SpanKind.SERVER,
+        attributes: {
+            "http.method": method,
+            "http.route": route,
+        },
+    });
+}
+//# sourceMappingURL=instrument.js.map

package/dist/tracing/instrument.js.map

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

package/dist/tracing/middleware.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Hono middleware for distributed tracing.
+ *
+ * Automatically creates OTel spans for HTTP requests and propagates
+ * correlation IDs via the `x-correlation-id` header.
+ *
+ * Adds to every request:
+ * - An OTel span with HTTP semantic attributes
+ * - A correlation ID (from header or auto-generated)
+ * - Response headers: x-correlation-id, x-trace-id
+ */
+import type { MiddlewareHandler } from "hono";
+/**
+ * Tracing middleware for Hono.
+ * Wraps each request in an OTel span and correlation context.
+ */
+export declare function tracingMiddleware(): MiddlewareHandler;
+//# sourceMappingURL=middleware.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/tracing/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAS9C;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,CAsDrD"}

package/dist/tracing/middleware.js

@@ -0,0 +1,69 @@
+/**
+ * Hono middleware for distributed tracing.
+ *
+ * Automatically creates OTel spans for HTTP requests and propagates
+ * correlation IDs via the `x-correlation-id` header.
+ *
+ * Adds to every request:
+ * - An OTel span with HTTP semantic attributes
+ * - A correlation ID (from header or auto-generated)
+ * - Response headers: x-correlation-id, x-trace-id
+ */
+import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import { getTracer } from "./init.js";
+import { generateCorrelationId, withCorrelation, CORRELATION_HEADER, } from "./correlation.js";
+/**
+ * Tracing middleware for Hono.
+ * Wraps each request in an OTel span and correlation context.
+ */
+export function tracingMiddleware() {
+    return async (c, next) => {
+        const tracer = getTracer();
+        const method = c.req.method;
+        const path = new URL(c.req.url).pathname;
+        // Extract or generate correlation ID
+        const incomingCorrelationId = c.req.header(CORRELATION_HEADER);
+        const correlationId = incomingCorrelationId || generateCorrelationId();
+        // Run the handler inside both an OTel span and correlation context
+        await withCorrelation(correlationId, async () => {
+            const span = tracer.startSpan(`HTTP ${method} ${path}`, {
+                kind: SpanKind.SERVER,
+                attributes: {
+                    "http.method": method,
+                    "http.route": path,
+                    "http.url": c.req.url,
+                    "dash.correlation_id": correlationId,
+                },
+            });
+            try {
+                await next();
+                const status = c.res.status;
+                span.setAttribute("http.status_code", status);
+                if (status >= 400) {
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: `HTTP ${status}`,
+                    });
+                }
+                else {
+                    span.setStatus({ code: SpanStatusCode.OK });
+                }
+            }
+            catch (err) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: err instanceof Error ? err.message : String(err),
+                });
+                span.recordException(err instanceof Error ? err : new Error(String(err)));
+                throw err;
+            }
+            finally {
+                span.end();
+            }
+            // Propagate correlation + trace IDs in response headers
+            c.header(CORRELATION_HEADER, correlationId);
+            c.header("x-trace-id", span.spanContext().traceId);
+        });
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/tracing/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/tracing/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAE1B;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACvB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;QAEzC,qCAAqC;QACrC,MAAM,qBAAqB,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;QAC/D,MAAM,aAAa,GAAG,qBAAqB,IAAI,qBAAqB,EAAE,CAAC;QAEvE,mEAAmE;QACnE,MAAM,eAAe,CAAC,aAAa,EAAE,KAAK,IAAI,EAAE;YAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,MAAM,IAAI,IAAI,EAAE,EAAE;gBACtD,IAAI,EAAE,QAAQ,CAAC,MAAM;gBACrB,UAAU,EAAE;oBACV,aAAa,EAAE,MAAM;oBACrB,YAAY,EAAE,IAAI;oBAClB,UAAU,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG;oBACrB,qBAAqB,EAAE,aAAa;iBACrC;aACF,CAAC,CAAC;YAEH,IAAI,CAAC;gBACH,MAAM,IAAI,EAAE,CAAC;gBAEb,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;gBAC5B,IAAI,CAAC,YAAY,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;gBAE9C,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;oBAClB,IAAI,CAAC,SAAS,CAAC;wBACb,IAAI,EAAE,cAAc,CAAC,KAAK;wBAC1B,OAAO,EAAE,QAAQ,MAAM,EAAE;qBAC1B,CAAC,CAAC;gBACL,CAAC;qBAAM,CAAC;oBACN,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC9C,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,SAAS,CAAC;oBACb,IAAI,EAAE,cAAc,CAAC,KAAK;oBAC1B,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;iBAC1D,CAAC,CAAC;gBACH,IAAI,CAAC,eAAe,CAClB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CACpD,CAAC;gBACF,MAAM,GAAG,CAAC;YACZ,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,CAAC;YAED,wDAAwD;YACxD,CAAC,CAAC,MAAM,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;YAC5C,CAAC,CAAC,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,CAAC;QACrD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/tracing/tracer.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Lightweight tracing for Core agent runtime.
+ *
+ * Hooks into RuntimeBus lifecycle events to automatically create trace spans
+ * for agent operations (spawn, pause, resume, terminate, complete, fail).
+ * Tracks parent→child agent relationships as nested spans within a trace.
+ *
+ * Trace/span IDs use W3C-compatible hex format for future OTel export.
+ */
+import type { RuntimeBus } from "../agents/runtime/bus.js";
+export interface Span {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    operationName: string;
+    agentId: string;
+    /** Linked task ID from the agent instance. */
+    taskId?: string;
+    startTime: string;
+    endTime?: string;
+    durationMs?: number;
+    status: "ok" | "error" | "running";
+    attributes: Record<string, string | number | boolean>;
+    events: SpanEvent[];
+}
+export interface SpanEvent {
+    name: string;
+    timestamp: string;
+    attributes?: Record<string, string | number | boolean>;
+}
+export interface Trace {
+    traceId: string;
+    rootSpanId: string;
+    startTime: string;
+    endTime?: string;
+    durationMs?: number;
+    spanCount: number;
+    status: "ok" | "error" | "running";
+    /** Label of the root agent (for display). */
+    label?: string;
+}
+export interface TraceDetail {
+    trace: Trace;
+    spans: Span[];
+}
+/** 16-byte (32 hex char) trace ID. */
+export declare function generateTraceId(): string;
+/** 8-byte (16 hex char) span ID. */
+export declare function generateSpanId(): string;
+export declare class Tracer {
+    /** All spans indexed by spanId. */
+    private readonly spans;
+    /** agentId → active spanId for that agent. */
+    private readonly activeSpans;
+    /** agentId → traceId (so child agents inherit the parent's trace). */
+    private readonly agentTraces;
+    /** traceId → set of spanIds. */
+    private readonly traceSpans;
+    /** traceId → root spanId. */
+    private readonly traceRoots;
+    /** Maximum number of completed traces to retain. */
+    private readonly maxTraces;
+    /** Ordered list of traceIds for eviction. */
+    private readonly traceOrder;
+    constructor(opts?: {
+        maxTraces?: number;
+    });
+    /** Start a new span. If parentAgentId is provided, joins that agent's trace. */
+    startSpan(opts: {
+        operationName: string;
+        agentId: string;
+        taskId?: string;
+        parentAgentId?: string;
+        attributes?: Record<string, string | number | boolean>;
+    }): Span;
+    /** Add an event to an active span. */
+    addEvent(spanId: string, name: string, attributes?: Record<string, string | number | boolean>): void;
+    /** Set attributes on a span. */
+    setAttributes(spanId: string, attributes: Record<string, string | number | boolean>): void;
+    /** End a span with a status. */
+    endSpan(spanId: string, status?: "ok" | "error"): void;
+    /**
+     * Attach to a RuntimeBus to automatically create spans from lifecycle events.
+     * Call this once during runtime initialization.
+     */
+    attachToBus(bus: RuntimeBus): void;
+    private handleLifecycleEvent;
+    /** Get a span by ID. */
+    getSpan(spanId: string): Span | undefined;
+    /** Get the active span for an agent. */
+    getActiveSpan(agentId: string): Span | undefined;
+    /** Get a trace summary by ID. */
+    getTrace(traceId: string): Trace | undefined;
+    /** Get full trace detail (summary + all spans). */
+    getTraceDetail(traceId: string): TraceDetail | undefined;
+    /** List recent traces, newest first. */
+    listTraces(opts?: {
+        limit?: number;
+        status?: "ok" | "error" | "running";
+    }): Trace[];
+    /** Get the trace ID associated with an agent. */
+    getAgentTraceId(agentId: string): string | undefined;
+    private evict;
+}
+//# 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;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAO3D,MAAM,WAAW,IAAI;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACtD,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,KAAK;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;IACnC,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAMD,sCAAsC;AACtC,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,oCAAoC;AACpC,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAMD,qBAAa,MAAM;IACjB,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IAEjD,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IAEzD,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IAEzD,gCAAgC;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAE7D,6BAA6B;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IAExD,oDAAoD;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;gBAE/B,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;IAQzC,gFAAgF;IAChF,SAAS,CAAC,IAAI,EAAE;QACd,aAAa,EAAE,MAAM,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;KACxD,GAAG,IAAI;IA8CR,sCAAsC;IACtC,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACrD,IAAI;IAWP,gCAAgC;IAChC,aAAa,CACX,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACpD,IAAI;IAMP,gCAAgC;IAChC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,IAAI,GAAG,OAAc,GAAG,IAAI;IAmB5D;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAwBlC,OAAO,CAAC,oBAAoB;IA8E5B,wBAAwB;IACxB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIzC,wCAAwC;IACxC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAKhD,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAwC5C,mDAAmD;IACnD,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAaxD,wCAAwC;IACxC,UAAU,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAA;KAAE,GAAG,KAAK,EAAE;IAenF,iDAAiD;IACjD,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAQpD,OAAO,CAAC,KAAK;CAkBd"}