maestro-core 0.2.1 → 0.2.3

package/dist/runtime/providers.js

@@ -0,0 +1,124 @@
+import { APICallError, RetryError } from 'ai';
+/**
+ * Provider-fallback helpers. Used by hosts that want OpenAI as a
+ * resilience fallback when the primary Anthropic call hits a transient
+ * failure mode.
+ *
+ * 0.2.0 ships the helpers but does NOT wrap `runChatTurn` with the
+ * retry loop — mid-stream provider switching is invasive enough to
+ * deserve its own design pass. Hosts compose retry themselves using
+ * these primitives:
+ *
+ *   try {
+ *     return await runChatTurn({ ..., models: anthropicModels })
+ *   } catch (e) {
+ *     if (shouldFallback(e)) {
+ *       return runChatTurn({
+ *         ...,
+ *         models: {
+ *           fast: mapModelIdToOpenAI(anthropicModels.fast),
+ *           smart: mapModelIdToOpenAI(anthropicModels.smart),
+ *         },
+ *       })
+ *     }
+ *     throw e
+ *   }
+ *
+ * Built-in retry wrapper tracked for 0.2.1.
+ */
+/**
+ * Returns true when the error suggests a transient provider failure
+ * worth retrying against a different provider (rate limit, 5xx,
+ * network error, timeout). Returns false for caller-side errors
+ * (auth, content policy, abort, intentional quota deny) so a real
+ * problem doesn't get masked by a successful fallback.
+ *
+ * Unwraps a single layer of `RetryError` (the AI SDK wraps the
+ * underlying APICallError after exhausting its internal retries) so
+ * the status-code logic applies to the root cause.
+ */
+export function shouldFallback(err) {
+    if (!(err instanceof Error))
+        return false;
+    // Intentional denies — never fallback.
+    if (err.name === 'AiQuotaDeniedError')
+        return false;
+    // User cancelled — never fallback; the stream would arrive after abort.
+    if (err.name === 'AbortError')
+        return false;
+    // Unwrap one layer of RetryError from the AI SDK.
+    if (RetryError.isInstance(err)) {
+        if (err.reason === 'abort')
+            return false;
+        const underlying = err.lastError;
+        if (underlying instanceof Error) {
+            return shouldFallback(underlying);
+        }
+        return false;
+    }
+    const message = err.message.toLowerCase();
+    // Content policy violation — real signal; OpenAI also refuses this content.
+    if (message.includes('content_policy') || message.includes('content policy')) {
+        return false;
+    }
+    // Network layer failures — transient infrastructure issues.
+    if (message.includes('econnrefused') ||
+        message.includes('enotfound') ||
+        message.includes('etimedout') ||
+        message.includes('fetch failed') ||
+        err.name === 'NetworkError' ||
+        err.name === 'FetchError') {
+        return true;
+    }
+    // Explicit timeout — likely provider degradation.
+    if (err.name === 'TimeoutError' || message.includes('timeout')) {
+        return true;
+    }
+    // Rate-limit phrase — providers sometimes format 429s as text-only
+    // messages without a clean status code in the string. Match by
+    // phrase before falling through to numeric extraction.
+    if (message.includes('rate limit') || message.includes('rate_limit')) {
+        return true;
+    }
+    const status = APICallError.isInstance(err)
+        ? (err.statusCode ?? 0)
+        : extractStatusCodeFromMessage(err);
+    if (status === 429)
+        return true; // rate limit
+    if (status >= 500 && status < 600)
+        return true; // server error
+    if (status === 400 || status === 401 || status === 403)
+        return false; // caller-side / auth
+    return false; // conservative default
+}
+/**
+ * Map an Anthropic model id to its OpenAI equivalent for the fallback
+ * path. Capability + cost parity:
+ *   - Haiku  → gpt-4o-mini  (fast, cheap)
+ *   - Sonnet → gpt-4o       (capable, mid-range)
+ *   - Opus   → gpt-4o       (closest available equivalent)
+ *   - Unknown → gpt-4o-mini (conservative default — cheaper)
+ *
+ * Anthropic model ids may include date suffixes
+ * (e.g. `claude-haiku-4-5-20251001`); the substring match handles all
+ * variants.
+ */
+export function mapModelIdToOpenAI(anthropicModelId) {
+    if (!anthropicModelId)
+        return 'gpt-4o-mini';
+    const id = anthropicModelId.toLowerCase();
+    if (id.includes('sonnet') || id.includes('opus'))
+        return 'gpt-4o';
+    return 'gpt-4o-mini';
+}
+/**
+ * Last-resort status-code parser. Matches patterns like "503 Service
+ * Unavailable" in error messages when the error is not an
+ * `APICallError` instance. Returns 0 when no valid HTTP code is found.
+ */
+function extractStatusCodeFromMessage(err) {
+    const match = err.message.match(/\b([45]\d{2})\b/);
+    const code = match?.[1];
+    return code ? parseInt(code, 10) : 0;
+}
+//# sourceMappingURL=providers.js.map

package/dist/runtime/providers.js.map

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

package/dist/runtime/quota.d.ts

@@ -0,0 +1,66 @@
+import type { QuotaState, QuotaStore } from '../ports/quota-store.js';
+/**
+ * Why this reason set: each value names the COUNTER that tripped,
+ * not the window or unit. Hosts compose their own UI-facing
+ * `tokens_per_day` / `cost_per_hour` strings from `reason + window`
+ * at render time. Keeping the kernel reason terse lets hosts use
+ * any window granularity (daily, hourly, monthly) without the
+ * kernel knowing about it.
+ */
+export type AiQuotaDenyReason = 'input_tokens' | 'output_tokens' | 'tool_calls' | 'cost_usd_micro';
+export interface AiQuotaDenyPayload {
+    reason: AiQuotaDenyReason;
+    /** Ceiling that was tripped, in the natural unit of `reason` (tokens, calls, micro-USD). */
+    ceiling: number;
+    /** Counter value at check time. May exceed `ceiling` due to race windows + post-call increments. */
+    current: number;
+    /** When the current window resets. Surface on the deny UX. */
+    windowEnd: Date;
+    tenantId: string;
+    surface: string;
+}
+/**
+ * Thrown by `runChatTurn` when the pre-call quota check finds a
+ * counter at or above its ceiling. Hosts catch this at the route
+ * boundary and translate to whatever HTTP error shape their client
+ * renders (e.g. barbeiro's `buildQuotaDenyPayload` → 429 with
+ * localized copy).
+ *
+ * Captured as a class (not a discriminated union) so `instanceof`
+ * works across module boundaries and frame-level `instanceof` checks
+ * survive bundler transforms. `payload` carries the structured data.
+ */
+export declare class AiQuotaDeniedError extends Error {
+    readonly name = "AiQuotaDeniedError";
+    readonly payload: AiQuotaDenyPayload;
+    constructor(payload: AiQuotaDenyPayload);
+}
+/**
+ * Inspect a `QuotaState` and throw on the first counter that has
+ * reached or exceeded its ceiling. Order of evaluation is fixed —
+ * `input_tokens` → `output_tokens` → `tool_calls` → `cost_usd_micro` —
+ * so the deny reason rendered to the user is stable across deploys.
+ *
+ * A `null`/undefined ceiling means "unbounded" and is skipped (the
+ * tenant has no cap on that counter). Counters with zero ceiling are
+ * treated the same as unbounded — a zero cap is almost always a
+ * misseed; failing every call would surface the bug as user pain
+ * instead of a dashboard alert.
+ */
+export declare function enforceQuotaOrThrow(args: {
+    tenantId: string;
+    surface: string;
+    state: QuotaState;
+}): void;
+/**
+ * Convenience: query the port and enforce in one call. The pre-call
+ * check inside `runChatTurn` uses this. Fail-open behaviour (swallow
+ * port errors and proceed) is the CALLER's choice — `runChatTurn`
+ * decides via its `failOpenOnQuotaError` flag.
+ */
+export declare function checkAndEnforce(args: {
+    quotaStore: QuotaStore;
+    tenantId: string;
+    surface: string;
+}): Promise<void>;
+//# sourceMappingURL=quota.d.ts.map

package/dist/runtime/quota.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota.d.ts","sourceRoot":"","sources":["../../src/runtime/quota.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAErE;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACvB,cAAc,GACd,eAAe,GACf,YAAY,GACZ,gBAAgB,CAAA;AAEtB,MAAM,WAAW,kBAAkB;IAC/B,MAAM,EAAE,iBAAiB,CAAA;IACzB,4FAA4F;IAC5F,OAAO,EAAE,MAAM,CAAA;IACf,oGAAoG;IACpG,OAAO,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,SAAS,EAAE,IAAI,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IACzC,SAAkB,IAAI,wBAAuB;IAC7C,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;gBAExB,OAAO,EAAE,kBAAkB;CAQ1C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACtC,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,UAAU,CAAA;CACpB,GAAG,IAAI,CA2DP;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IACxC,UAAU,EAAE,UAAU,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB"}

package/dist/runtime/quota.js

@@ -0,0 +1,102 @@
+/**
+ * Thrown by `runChatTurn` when the pre-call quota check finds a
+ * counter at or above its ceiling. Hosts catch this at the route
+ * boundary and translate to whatever HTTP error shape their client
+ * renders (e.g. barbeiro's `buildQuotaDenyPayload` → 429 with
+ * localized copy).
+ *
+ * Captured as a class (not a discriminated union) so `instanceof`
+ * works across module boundaries and frame-level `instanceof` checks
+ * survive bundler transforms. `payload` carries the structured data.
+ */
+export class AiQuotaDeniedError extends Error {
+    name = 'AiQuotaDeniedError';
+    payload;
+    constructor(payload) {
+        super(`AI quota exceeded: ${payload.reason} on ${payload.surface} for tenant ${payload.tenantId} (${payload.current}/${payload.ceiling})`);
+        this.payload = payload;
+        // Restore the prototype chain across bundler transforms.
+        Object.setPrototypeOf(this, AiQuotaDeniedError.prototype);
+    }
+}
+/**
+ * Inspect a `QuotaState` and throw on the first counter that has
+ * reached or exceeded its ceiling. Order of evaluation is fixed —
+ * `input_tokens` → `output_tokens` → `tool_calls` → `cost_usd_micro` —
+ * so the deny reason rendered to the user is stable across deploys.
+ *
+ * A `null`/undefined ceiling means "unbounded" and is skipped (the
+ * tenant has no cap on that counter). Counters with zero ceiling are
+ * treated the same as unbounded — a zero cap is almost always a
+ * misseed; failing every call would surface the bug as user pain
+ * instead of a dashboard alert.
+ */
+export function enforceQuotaOrThrow(args) {
+    const { ceilings, used, windowEnd } = args.state;
+    if (typeof ceilings.maxTokensIn === 'number' &&
+        ceilings.maxTokensIn > 0 &&
+        used.tokensIn >= ceilings.maxTokensIn) {
+        throw new AiQuotaDeniedError({
+            reason: 'input_tokens',
+            ceiling: ceilings.maxTokensIn,
+            current: used.tokensIn,
+            windowEnd,
+            tenantId: args.tenantId,
+            surface: args.surface,
+        });
+    }
+    if (typeof ceilings.maxTokensOut === 'number' &&
+        ceilings.maxTokensOut > 0 &&
+        used.tokensOut >= ceilings.maxTokensOut) {
+        throw new AiQuotaDeniedError({
+            reason: 'output_tokens',
+            ceiling: ceilings.maxTokensOut,
+            current: used.tokensOut,
+            windowEnd,
+            tenantId: args.tenantId,
+            surface: args.surface,
+        });
+    }
+    if (typeof ceilings.maxCallsPerWindow === 'number' &&
+        ceilings.maxCallsPerWindow > 0 &&
+        used.calls >= ceilings.maxCallsPerWindow) {
+        throw new AiQuotaDeniedError({
+            reason: 'tool_calls',
+            ceiling: ceilings.maxCallsPerWindow,
+            current: used.calls,
+            windowEnd,
+            tenantId: args.tenantId,
+            surface: args.surface,
+        });
+    }
+    if (typeof ceilings.maxUsdMicro === 'number' &&
+        ceilings.maxUsdMicro > 0 &&
+        used.usdMicro >= ceilings.maxUsdMicro) {
+        throw new AiQuotaDeniedError({
+            reason: 'cost_usd_micro',
+            ceiling: ceilings.maxUsdMicro,
+            current: used.usdMicro,
+            windowEnd,
+            tenantId: args.tenantId,
+            surface: args.surface,
+        });
+    }
+}
+/**
+ * Convenience: query the port and enforce in one call. The pre-call
+ * check inside `runChatTurn` uses this. Fail-open behaviour (swallow
+ * port errors and proceed) is the CALLER's choice — `runChatTurn`
+ * decides via its `failOpenOnQuotaError` flag.
+ */
+export async function checkAndEnforce(args) {
+    const state = await args.quotaStore.check({
+        tenantId: args.tenantId,
+        surface: args.surface,
+    });
+    enforceQuotaOrThrow({
+        tenantId: args.tenantId,
+        surface: args.surface,
+        state,
+    });
+}
+//# sourceMappingURL=quota.js.map

package/dist/runtime/quota.js.map

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

package/dist/runtime/run-chat-turn.d.ts

@@ -0,0 +1,145 @@
+import { type UIMessage } from 'ai';
+import type { BaseToolContext } from '../context.js';
+import { type ModelTier } from '../models.js';
+import type { AuditStore } from '../ports/audit-store.js';
+import { type Clock } from '../ports/clock.js';
+import type { ModelKeyProvider } from '../ports/key-provider.js';
+import { type Logger } from '../ports/logger.js';
+import type { MemoryStore } from '../ports/memory-store.js';
+import type { QuotaStore } from '../ports/quota-store.js';
+import { type TelemetrySink } from '../ports/telemetry-sink.js';
+import type { TurnRecord, TurnStore } from '../ports/turn-store.js';
+import type { AgentToolDefinition } from '../tool.js';
+/**
+ * Public chat-turn entry point. One call replaces the ~300 LoC of stream
+ * orchestration a host route would otherwise write by hand
+ * (build tools, call streamText, persist turn, emit telemetry, handle
+ * errors, return SSE response).
+ *
+ * Current scope (slice 4):
+ *   ✓ Model selection via `selectChatModel`
+ *   ✓ Provider key resolution via `ModelKeyProvider` port
+ *   ✓ AI SDK tool building via the `buildAiSdkTools` adapter
+ *   ✓ Turn persistence via `TurnStore` port (pending → completed | failed | aborted)
+ *   ✓ Telemetry emit via `TelemetrySink` port (default Noop)
+ *   ✓ Cost estimate via `estimateCost`
+ *   ✓ SSE Response ready to return from a Next.js route
+ *   ✓ Pre-call quota gate via `QuotaStore.check` (throws `AiQuotaDeniedError` on deny)
+ *   ✓ Post-call quota record via `QuotaStore.record` (fire-and-forget)
+ *   ✓ Memory load via `MemoryStore.load` (formatted into dynamic system segment)
+ *   ✓ Anthropic prompt-cache breakpoints via `applyCacheBreakpoints`
+ *
+ * Deferred to later slices / releases:
+ *   ☐ Empty-recovery classifier — exposed as a helper in slice 5;
+ *     calling routes decide what to do with the signal.
+ *   ☐ OpenAI fallback retry wrapper inside runChatTurn — slice 5
+ *     ships the helper primitives (`shouldFallback`, `mapModelToOpenAI`)
+ *     so hosts can compose the retry themselves. Built-in retry
+ *     wrapper deferred to 0.2.1 — mid-stream switching is invasive.
+ */
+export interface RunChatTurnPorts {
+    turnStore: TurnStore;
+    keyProvider: ModelKeyProvider;
+    auditStore?: AuditStore;
+    /** Reserved for slice 3. Currently unused — pass when ready. */
+    quotaStore?: QuotaStore;
+    /** Reserved for slice 4. Currently unused — pass when ready. */
+    memoryStore?: MemoryStore;
+    telemetry?: TelemetrySink;
+    clock?: Clock;
+    logger?: Logger;
+}
+export interface RunChatTurnArgs<TCtx extends BaseToolContext> {
+    /** Stable id grouping this turn into a conversation. */
+    threadId: string;
+    /** Per-request context. */
+    ctx: TCtx;
+    /** UI messages from the client (`@ai-sdk/react` shape). */
+    messages: UIMessage[];
+    /** Eligible tool registry — host pre-filters for surface/availability. */
+    tools: readonly AgentToolDefinition<any, any, TCtx>[];
+    /**
+     * Split system prompt for Anthropic prompt-cache hits.
+     *
+     *   `static`  — tenant-invariant content. Hashed for the cache key.
+     *               MUST NOT contain per-tenant interpolated strings;
+     *               numbers / IDs are fine if they live in `dynamic`
+     *               instead.
+     *   `dynamic` — tenant-specific content (timezone label, business
+     *               name in prose, current time, memory facts). Rendered
+     *               after the cache breakpoint so it never influences
+     *               the cache key. Optional — omit if there's nothing
+     *               tenant-specific to inject.
+     *
+     * Memory facts loaded via the `MemoryStore` port are auto-appended
+     * to `dynamic` before the cache split — hosts don't need to format
+     * them in by hand.
+     */
+    systemPrompt: {
+        static: string;
+        dynamic?: string;
+    };
+    /** Per-tier model ids. Host resolves from its env layer. */
+    models: {
+        fast: string;
+        smart: string;
+        force?: string | null;
+    };
+    /** Optional hint that bypasses the model heuristic for this turn. */
+    modelHint?: {
+        tier?: ModelTier;
+    };
+    /** Forwarded to streamText for client-side cancellation. */
+    abortSignal?: AbortSignal;
+    /** Required ports + optional advanced ports. */
+    ports: RunChatTurnPorts;
+    /** Side-effect hook after the assistant turn row is finalised. */
+    onTurnFinalized?: (turn: TurnRecord) => void | Promise<void>;
+    /**
+     * When true (default) and `ports.quotaStore` is supplied, a thrown
+     * error from the port's `check` method is logged at warn and the
+     * call proceeds anyway. Matches the barbeiro convention — never
+     * block paying customers on a transient Redis blip. Pre-call
+     * `AiQuotaDeniedError` throws (which are intentional) propagate
+     * regardless of this flag.
+     *
+     * Set to false in environments where the deny path must be
+     * strictly authoritative (compliance, internal-test fixtures).
+     */
+    failOpenOnQuotaError?: boolean;
+    /**
+     * Optional namespace passed to `MemoryStore.load` so a host that
+     * partitions facts (e.g. `'preferences'` vs `'facts'`) can scope
+     * the load. Omit for the default unscoped lookup. Has no effect
+     * when `ports.memoryStore` is not supplied.
+     */
+    memoryNamespace?: string;
+    /**
+     * Optional host-supplied turn id. When provided, the kernel uses
+     * it verbatim for the assistant `TurnRecord.id`. When omitted, the
+     * kernel generates one via the existing
+     * `turn_<epoch>_<requestId?>_<rand>` shape.
+     *
+     * Hosts whose persistence layer uses a different id space
+     * (incrementing integers, externally-supplied UUIDs) pass their
+     * id here so the port impl can update the row by its real key
+     * instead of maintaining a `kernelTurnId → hostRowId` mapping. The
+     * port impl is responsible for parsing the id back to its native
+     * shape (e.g. `Number(turn.id)` for integer primary keys).
+     *
+     * Added in 0.2.1; pre-existing callers continue to get
+     * kernel-generated ids unchanged.
+     */
+    turnId?: string;
+    /**
+     * Max steps in the tool-use loop. Default `5` — leaves headroom for
+     * a few tool round-trips per turn without runaway loops. AI SDK
+     * counts each model response as a step; without this hint, the
+     * SDK stops after the FIRST response, meaning tool results never
+     * feed back to the model (the user sees the empty bubble after a
+     * tool call). Set higher for agents that do deep multi-step work.
+     */
+    maxSteps?: number;
+}
+export declare function runChatTurn<TCtx extends BaseToolContext>(args: RunChatTurnArgs<TCtx>): Promise<Response>;
+//# sourceMappingURL=run-chat-turn.d.ts.map

package/dist/runtime/run-chat-turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-chat-turn.d.ts","sourceRoot":"","sources":["../../src/runtime/run-chat-turn.ts"],"names":[],"mappings":"AACA,OAAO,EAAmD,KAAK,SAAS,EAAE,MAAM,IAAI,CAAA;AAIpF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,cAAc,CAAA;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,KAAK,KAAK,EAAe,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAChE,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,oBAAoB,CAAA;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAClF,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AACnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAKrD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,gBAAgB;IAC7B,SAAS,EAAE,SAAS,CAAA;IACpB,WAAW,EAAE,gBAAgB,CAAA;IAC7B,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,gEAAgE;IAChE,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,gEAAgE;IAChE,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,SAAS,CAAC,EAAE,aAAa,CAAA;IACzB,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,eAAe,CAAC,IAAI,SAAS,eAAe;IACzD,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAA;IAChB,2BAA2B;IAC3B,GAAG,EAAE,IAAI,CAAA;IACT,2DAA2D;IAC3D,QAAQ,EAAE,SAAS,EAAE,CAAA;IACrB,0EAA0E;IAC1E,KAAK,EAAE,SAAS,mBAAmB,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,CAAA;IACrD;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAClD,4DAA4D;IAC5D,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;IAC9D,qEAAqE;IACrE,SAAS,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,SAAS,CAAA;KAAE,CAAA;IAChC,4DAA4D;IAC5D,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,gDAAgD;IAChD,KAAK,EAAE,gBAAgB,CAAA;IACvB,kEAAkE;IAClE,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5D;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,wBAAsB,WAAW,CAAC,IAAI,SAAS,eAAe,EAC1D,IAAI,EAAE,eAAe,CAAC,IAAI,CAAC,GAC5B,OAAO,CAAC,QAAQ,CAAC,CAwUnB"}