@verevoir/review 0.3.0 → 0.3.2

package/node_modules/@verevoir/llm/dist/otel.js

@@ -0,0 +1,194 @@
+/**
+ * @verevoir/llm — OpenTelemetry GenAI client spans.
+ *
+ * One CLIENT span per provider call, named `chat {model}`, carrying the
+ * OpenTelemetry Semantic Conventions for Generative AI attributes this file
+ * defines as local string constants — NOT imported from
+ * `@opentelemetry/semantic-conventions/incubating`. Per OTel's own guidance
+ * for conventions still in the Development state, an instrumentation
+ * library pins the attribute *names* it needs locally rather than taking a
+ * dependency on an incubating entry point whose shape is still moving
+ * (https://opentelemetry.io/docs/specs/semconv/general/attribute-naming/).
+ *
+ * Followed: OpenTelemetry Semantic Conventions for Generative AI, v1.37.0
+ * (`gen_ai.*`, status: Development) —
+ * https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/gen-ai/gen-ai-spans.md
+ * In that version `gen_ai.provider.name` is the current provider attribute;
+ * the earlier `gen_ai.system` is deprecated in favour of it.
+ *
+ * Cache tokens and the provider's own request id are NOT part of that spec
+ * as of v1.37.0 — there is no `gen_ai.usage.cache_*` attribute and no
+ * `gen_ai.*request_id` attribute defined. The four fields below are this
+ * project's own, deliberately namespaced OUTSIDE `gen_ai.*` (under
+ * `verevoir.llm.*`) so a reader never mistakes them for a standard
+ * attribute: `cache_read_input_tokens`, `cache_creation_input_tokens`,
+ * `cache_creation.ephemeral_5m_input_tokens`,
+ * `cache_creation.ephemeral_1h_input_tokens`, and `provider_request_id`.
+ *
+ * This module depends only on `@opentelemetry/api` — never an SDK. With no
+ * SDK/exporter installed by the consuming application, `trace.getTracer()`
+ * returns the API's own no-op tracer, so every span created here costs
+ * nothing and changes no behaviour until an application wires up a real
+ * provider — see `otel.test.ts`'s "no SDK installed" case. v5 of this
+ * monorepo is where an SDK + exporter gets installed (ADR 046: this package
+ * is the only one that talks to a provider SDK, so it is the right place
+ * for the per-call span).
+ */
+import { SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
+// ── GenAI semantic-convention attributes (v1.37.0) — defined locally ───────
+/** The kind of GenAI operation this span represents. Every call this
+ * package instruments is a `"chat"` operation. */
+export const ATTR_GEN_AI_OPERATION_NAME = 'gen_ai.operation.name';
+/** The GenAI provider, e.g. `anthropic`, `openai`, `google`. Replaces the
+ * now-deprecated `gen_ai.system` as of semconv v1.37.0. */
+export const ATTR_GEN_AI_PROVIDER_NAME = 'gen_ai.provider.name';
+/** The model id requested. */
+export const ATTR_GEN_AI_REQUEST_MODEL = 'gen_ai.request.model';
+/** The model id the provider actually answered with — may differ from the
+ * request (e.g. an alias resolving to a dated snapshot). */
+export const ATTR_GEN_AI_RESPONSE_MODEL = 'gen_ai.response.model';
+/** The provider's own id for this response. */
+export const ATTR_GEN_AI_RESPONSE_ID = 'gen_ai.response.id';
+/** Tokens in the request (prompt). */
+export const ATTR_GEN_AI_USAGE_INPUT_TOKENS = 'gen_ai.usage.input_tokens';
+/** Tokens in the response (completion). */
+export const ATTR_GEN_AI_USAGE_OUTPUT_TOKENS = 'gen_ai.usage.output_tokens';
+/** General (non-GenAI-specific) semconv attribute for the type of error
+ * that failed the span — the thrown error's `name`. */
+export const ATTR_ERROR_TYPE = 'error.type';
+// ── Custom attributes — NOT in GenAI semconv v1.37.0; namespaced outside
+// `gen_ai.*` so they read unambiguously as this project's own. ─────────────
+/** Tokens read from provider cache on this call. Custom: no `gen_ai.*`
+ * attribute for this exists in v1.37.0. */
+export const ATTR_VEREVOIR_CACHE_READ_INPUT_TOKENS = 'verevoir.llm.cache_read_input_tokens';
+/** Tokens written to provider cache on this call. Custom — see above. */
+export const ATTR_VEREVOIR_CACHE_CREATION_INPUT_TOKENS = 'verevoir.llm.cache_creation_input_tokens';
+/** Anthropic's 5-minute-TTL slice of the cache-write tokens. Custom — see
+ * above; this mirrors Anthropic's own wire field name
+ * (`usage.cache_creation.ephemeral_5m_input_tokens`). */
+export const ATTR_VEREVOIR_CACHE_CREATION_EPHEMERAL_5M_INPUT_TOKENS = 'verevoir.llm.cache_creation.ephemeral_5m_input_tokens';
+/** Anthropic's 1-hour-TTL slice of the cache-write tokens — see above. */
+export const ATTR_VEREVOIR_CACHE_CREATION_EPHEMERAL_1H_INPUT_TOKENS = 'verevoir.llm.cache_creation.ephemeral_1h_input_tokens';
+/** The provider's own id for this call — an HTTP `request-id` header where
+ * reachable, or the SDK response object's own id field otherwise (see
+ * `TokenUsage.providerRequestId` in src/index.ts for which adapters set
+ * which). Custom: no `gen_ai.*` attribute for this exists in v1.37.0. */
+export const ATTR_VEREVOIR_PROVIDER_REQUEST_ID = 'verevoir.llm.provider_request_id';
+/** claude-cli only: the CLI's own session id, kept for correlation — NOT
+ * a per-call request id. A held session reuses this across every turn;
+ * see `TokenUsage.sessionId`'s own doc comment for why it is a separate
+ * field from {@link ATTR_VEREVOIR_PROVIDER_REQUEST_ID}. */
+export const ATTR_VEREVOIR_SESSION_ID = 'verevoir.llm.session_id';
+/** The provider's own reported cost for this call, in USD. Custom: no
+ * `gen_ai.*` cost attribute exists in v1.37.0, and this is deliberately
+ * the provider's own relayed figure, never a value this library computed
+ * from a price table. */
+export const ATTR_VEREVOIR_COST_USD_REPORTED = 'verevoir.llm.cost_usd_reported';
+const tracer = trace.getTracer('@verevoir/llm');
+/**
+ * ══════════════════════════════════════════════════════════════════════
+ * WHY SPANS NEVER CARRY ERROR MESSAGES.
+ * ══════════════════════════════════════════════════════════════════════
+ * A privacy audit (2026-10-22) found three real paths for provider or
+ * response text to reach a span through the raw error object
+ * `recordException` used to record verbatim:
+ *   - claude-cli's `is_error: true` throws embed the CLI's own response
+ *     text (`parsed.result`) directly in the error message — see
+ *     src/claude-cli/index.ts's one-shot path and src/claude-cli/
+ *     session.ts's held-session path, both around their `is_error`
+ *     check. That text can be the model's own output for the call.
+ *   - every other adapter rethrows its SDK's own error unchanged out of
+ *     its `callWithRetries`; this library does not control what those
+ *     SDKs put in `.message`, which can include a copy of the request or
+ *     response body.
+ *   - `recordException`'s standard behaviour also captures the error's
+ *     `.stack`, which — being a Node stack trace — carries local
+ *     filesystem paths.
+ * `withGenAISpan` below records a SANITIZED stand-in instead of the raw
+ * error: the error's `name`, plus a numeric HTTP status if the error
+ * happens to carry one (`.status`/`.statusCode`, as the OpenAI/Anthropic
+ * SDKs set) — never the error's own `.message` and never `.stack`. The
+ * error rethrown to the CALLER below is the original, untouched object;
+ * only what reaches the span is sanitized.
+ */
+/** Best-effort numeric HTTP status off an error, if the SDK that threw it
+ * sets one (OpenAI/Anthropic-shaped errors use `.status`; some others use
+ * `.statusCode`). `undefined` when neither is a number — never guessed,
+ * and never derived from the error's message text. */
+function extractHttpStatus(err) {
+    if (!err || typeof err !== 'object')
+        return undefined;
+    const status = err.status;
+    if (typeof status === 'number')
+        return status;
+    const statusCode = err.statusCode;
+    if (typeof statusCode === 'number')
+        return statusCode;
+    return undefined;
+}
+/**
+ * Run `fn` inside a CLIENT span named `chat {requestModel}` — the GenAI
+ * semconv span-naming convention, `{gen_ai.operation.name} {gen_ai.request
+ * .model}`. `fn` receives the live span (for a caller that wants to add
+ * more of its own) and returns both its own result and the
+ * {@link GenAISpanOutcome} to record.
+ *
+ * On success, every PRESENT outcome field becomes a span attribute and the
+ * span ends OK. On throw, `error.type` is set to the error's `name`, a
+ * SANITIZED exception (name + a content-free summary, never the error's
+ * own message or stack — see WHY SPANS NEVER CARRY ERROR MESSAGES above)
+ * is recorded on the span, the span ends ERROR with that same sanitized
+ * message, and the error is rethrown to the CALLER completely unchanged —
+ * this never swallows, wraps, or reshapes a failure for the caller; it
+ * only changes what the span itself is allowed to observe.
+ */
+export async function withGenAISpan(request, fn) {
+    return tracer.startActiveSpan(`chat ${request.requestModel}`, {
+        kind: SpanKind.CLIENT,
+        attributes: {
+            [ATTR_GEN_AI_OPERATION_NAME]: 'chat',
+            [ATTR_GEN_AI_PROVIDER_NAME]: request.provider,
+            [ATTR_GEN_AI_REQUEST_MODEL]: request.requestModel,
+        },
+    }, async (span) => {
+        try {
+            const { result, outcome } = await fn(span);
+            applyOutcome(span, outcome);
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (err) {
+            const errorType = err instanceof Error && err.name ? err.name : 'Error';
+            const httpStatus = extractHttpStatus(err);
+            const sanitizedMessage = httpStatus !== undefined ? `${errorType} (status ${httpStatus})` : errorType;
+            span.setAttribute(ATTR_ERROR_TYPE, errorType);
+            // SANITIZED exception — never the real error's message or stack.
+            // See "WHY SPANS NEVER CARRY ERROR MESSAGES" above. The error
+            // rethrown to the caller below is the original, untouched object.
+            span.recordException({ name: errorType, message: sanitizedMessage });
+            span.setStatus({ code: SpanStatusCode.ERROR, message: sanitizedMessage });
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+function applyOutcome(span, outcome) {
+    const set = (key, value) => {
+        if (value !== undefined)
+            span.setAttribute(key, value);
+    };
+    set(ATTR_GEN_AI_RESPONSE_MODEL, outcome.responseModel);
+    set(ATTR_GEN_AI_RESPONSE_ID, outcome.responseId);
+    set(ATTR_GEN_AI_USAGE_INPUT_TOKENS, outcome.inputTokens);
+    set(ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, outcome.outputTokens);
+    set(ATTR_VEREVOIR_CACHE_READ_INPUT_TOKENS, outcome.cacheReadInputTokens);
+    set(ATTR_VEREVOIR_CACHE_CREATION_INPUT_TOKENS, outcome.cacheCreationInputTokens);
+    set(ATTR_VEREVOIR_CACHE_CREATION_EPHEMERAL_5M_INPUT_TOKENS, outcome.cacheCreationEphemeral5mInputTokens);
+    set(ATTR_VEREVOIR_CACHE_CREATION_EPHEMERAL_1H_INPUT_TOKENS, outcome.cacheCreationEphemeral1hInputTokens);
+    set(ATTR_VEREVOIR_SESSION_ID, outcome.sessionId);
+    set(ATTR_VEREVOIR_PROVIDER_REQUEST_ID, outcome.providerRequestId);
+    set(ATTR_VEREVOIR_COST_USD_REPORTED, outcome.costUsdReported);
+}
+//# sourceMappingURL=otel.js.map

package/node_modules/@verevoir/llm/dist/otel.js.map

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

package/node_modules/@verevoir/llm/dist/pair.d.ts

@@ -0,0 +1,46 @@
+import type { ChatOptions, ChatReply, TokenUsage, ToolDef, ToolExecutor } from './index.js';
+/** One completed consult — what the executor asked, what the advisor said. */
+export interface ConsultInfo {
+    /** The executor's question, verbatim from the tool call. */
+    question: string;
+    /** The excerpt the executor attached, when it attached one. */
+    context?: string;
+    /** The advisor's reply text, as returned to the executor. */
+    answer: string;
+    /** The advisor call's usage, when the bound `chat` reported it via `onUsage`. */
+    usage?: TokenUsage;
+}
+/** How to reach the advisor and how it should judge. */
+export interface AdvisorConfig {
+    /** Any adapter's `chat`, caller-bound — the advisor model behind the tool. */
+    chat: (opts: ChatOptions) => Promise<ChatReply>;
+    /** The bar the advisor holds — its system prompt for every consult. */
+    systemPrompt: string;
+    /** Override for the consult tool's name. Default `consult_advisor`. */
+    toolName?: string;
+    /** Override for the consult tool's description — the consult-calibration lever. */
+    description?: string;
+    /**
+     * Consult-rate metrics hook, fired after each successful consult. Fail-soft:
+     * a throw is caught and warned, never breaking the consult. NOT fired when
+     * the advisor call itself fails — there is no answer to report.
+     */
+    onConsult?: (info: ConsultInfo) => void;
+}
+/**
+ * Wrap a tool set + executor so the model can consult a stronger advisor.
+ * Returns a NEW tools array with the consult tool appended (the input is never
+ * mutated) and an executor that routes consult calls to `advisor.chat` — every
+ * other tool call passes through to `executor` untouched. Pass the result to
+ * any adapter's `chatWithToolLoop`.
+ *
+ * A tool already named like the consult tool is a programmer error: throws at
+ * wrap time. A failing advisor is a runtime condition: the wrapped executor
+ * returns a legible "advisor unavailable" result instead of throwing, so a
+ * dead advisor never kills the work.
+ */
+export declare function withAdvisor(tools: ToolDef[], executor: ToolExecutor, advisor: AdvisorConfig): {
+    tools: ToolDef[];
+    executor: ToolExecutor;
+};
+//# sourceMappingURL=pair.d.ts.map

package/node_modules/@verevoir/llm/dist/pair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pair.d.ts","sourceRoot":"","sources":["../src/pair.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK5F,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,IAAI,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IAChD,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;CACzC;AAUD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,EAAE,EAChB,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,aAAa,GACrB;IAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,CA4B9C"}

package/node_modules/@verevoir/llm/dist/pair.js

@@ -0,0 +1,105 @@
+const DEFAULT_TOOL_NAME = 'consult_advisor';
+const DEFAULT_DESCRIPTION = 'Consult your senior advisor when you hit a decision you cannot confidently resolve: ' +
+    'a design choice, whether your work meets the required practices, an ambiguous ' +
+    'requirement, before an irreversible action, and before declaring the task done. ' +
+    'Ask one specific question and include only the relevant excerpt.';
+/**
+ * Wrap a tool set + executor so the model can consult a stronger advisor.
+ * Returns a NEW tools array with the consult tool appended (the input is never
+ * mutated) and an executor that routes consult calls to `advisor.chat` — every
+ * other tool call passes through to `executor` untouched. Pass the result to
+ * any adapter's `chatWithToolLoop`.
+ *
+ * A tool already named like the consult tool is a programmer error: throws at
+ * wrap time. A failing advisor is a runtime condition: the wrapped executor
+ * returns a legible "advisor unavailable" result instead of throwing, so a
+ * dead advisor never kills the work.
+ */
+export function withAdvisor(tools, executor, advisor) {
+    const toolName = advisor.toolName ?? DEFAULT_TOOL_NAME;
+    if (tools.some((t) => t.name === toolName)) {
+        throw new Error(`withAdvisor: a tool named "${toolName}" already exists — rename it or set advisor.toolName`);
+    }
+    const consultTool = {
+        name: toolName,
+        description: advisor.description ?? DEFAULT_DESCRIPTION,
+        input_schema: {
+            type: 'object',
+            properties: {
+                question: {
+                    type: 'string',
+                    description: 'The specific decision or uncertainty; be concrete.',
+                },
+                context: {
+                    type: 'string',
+                    description: 'Only the relevant excerpt, not the whole transcript.',
+                },
+            },
+            required: ['question'],
+        },
+    };
+    const wrapped = async (toolUse) => toolUse.name === toolName ? consult(toolUse.input, advisor, toolName) : executor(toolUse);
+    return { tools: [...tools, consultTool], executor: wrapped };
+}
+/**
+ * Build the advisor's user-turn message from the tool call's `question` +
+ * optional `context`, following `src/claude-cli/index.ts`'s `joinTurns()`
+ * shape — role-labelled sections joined by a blank line — rather than the
+ * bare `${question}\n\n${context}` concatenation this used to be. Both
+ * `question` and `context` are model-supplied (`context` is documented to
+ * the model, in this file's `DEFAULT_DESCRIPTION`, as "the relevant
+ * excerpt" — plausibly tool-output text in a real loop), so a boundary
+ * that just disappears into the surrounding text is the actual defect
+ * being fixed here, not a cosmetic one.
+ *
+ * NOT A SECURITY BOUNDARY: a crafted `context` containing the literal text
+ * `"\n\n## question\n"` can still visually forge a second section once it
+ * reaches the advisor — see `pair.test.ts`'s dedicated test for exactly
+ * this, which documents the behaviour rather than hiding it. Labelling
+ * makes the intended structure legible to a reader (or a reviewer diffing
+ * the two strings); it does not, and is not claimed to, make the advisor
+ * unable to be confused by adversarial content embedded in `context`.
+ * Closing that would mean escaping or rejecting caller content — a
+ * heavier answer than this fix's scope, which is naming the limit
+ * honestly rather than pretending it's closed.
+ */
+function buildConsultMessage(question, context) {
+    if (!context)
+        return question;
+    return `## question\n${question}\n\n## context\n${context}`;
+}
+async function consult(input, advisor, toolName) {
+    const question = typeof input.question === 'string' ? input.question : '';
+    if (!question) {
+        return `${toolName} requires a question — call it again with a specific question`;
+    }
+    const context = typeof input.context === 'string' && input.context ? input.context : undefined;
+    let usage;
+    let reply;
+    try {
+        reply = await advisor.chat({
+            systemPrompt: advisor.systemPrompt,
+            turns: [{ role: 'user', content: buildConsultMessage(question, context) }],
+            modelClass: 'reasoning',
+            onUsage: async (u) => {
+                usage = u;
+            },
+        });
+    }
+    catch (err) {
+        // A dead advisor must not kill the work: the loop's is_error plumbing is
+        // for the inner executor's throws, so return a legible result instead.
+        const message = err instanceof Error ? err.message : String(err);
+        return `advisor unavailable: ${message} — proceed on your own judgement and note the uncertainty`;
+    }
+    if (advisor.onConsult) {
+        try {
+            advisor.onConsult({ question, context, answer: reply.content, usage });
+        }
+        catch (err) {
+            console.warn('withAdvisor: onConsult callback threw', err);
+        }
+    }
+    return reply.content;
+}
+//# sourceMappingURL=pair.js.map

package/node_modules/@verevoir/llm/dist/pair.js.map

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

package/node_modules/@verevoir/llm/dist/pricing-snapshot.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @verevoir/llm — bundled fallback price snapshot.
+ *
+ * `createPriceBook` (see `src/pricing.ts`) uses this as its DEFAULT
+ * fallback table — in effect only until the first successful live
+ * fetch replaces it. `refresh()` only ever assigns the table on
+ * success, so once a live fetch has succeeded once, a later failed
+ * refresh keeps that last good LIVE table rather than falling back to
+ * this snapshot again — unless the caller injects its own
+ * `PriceBookOptions.snapshot`. `payload` is a TRIMMED
+ * LiteLLM `model_prices_and_context_window.json`: model key → only the
+ * fields `src/pricing.ts`'s parser reads, in their original snake_case
+ * shape, so the exact same parser that reads a live fetch's body reads
+ * this too.
+ *
+ * Generated OUTSIDE the belt (the belt cannot reach the network): the
+ * upstream file was fetched, trimmed to the anthropic, openai, gemini,
+ * deepseek, mistral and sambanova providers and to the six fields above,
+ * and written here with its `asOf`, `sourceUrl` and the `sha256` of the
+ * raw upstream bytes. `sourceUrl` is pinned to the upstream commit, so
+ * `curl -sL <sourceUrl> | shasum -a 256` reproduces `sha256`. Do not
+ * hand-edit prices into it; regenerate it.
+ */
+export interface PricingSnapshot {
+    /** When this snapshot was generated, as an ISO 8601 UTC timestamp. */
+    asOf: string;
+    /** Where `payload` was trimmed from. */
+    sourceUrl: string;
+    /** sha256 of the raw upstream JSON this snapshot was trimmed from —
+     * of the raw upstream bytes. */
+    sha256: string;
+    /** Model key → only the fields `src/pricing.ts`'s parser reads
+     * (`input_cost_per_token`, `output_cost_per_token`,
+     * `cache_creation_input_token_cost`,
+     * `cache_creation_input_token_cost_above_1hr`,
+     * `cache_read_input_token_cost`, `litellm_provider`), untouched
+     * snake_case — the same shape a live fetch's JSON body is in. */
+    payload: Record<string, Record<string, unknown>>;
+}
+export declare const PRICING_SNAPSHOT: PricingSnapshot;
+//# sourceMappingURL=pricing-snapshot.d.ts.map

package/node_modules/@verevoir/llm/dist/pricing-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing-snapshot.d.ts","sourceRoot":"","sources":["../src/pricing-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB;oCACgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf;;;;;qEAKiE;IACjE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD;AAED,eAAO,MAAM,gBAAgB,EAAE,eAu5D9B,CAAC"}