@sensigo/realm-cli 0.1.0

package/dist/agent/providers/anthropic-provider.js

@@ -0,0 +1,257 @@
+// anthropic-provider.ts — Anthropic LLM provider implementation for realm agent.
+// Requires @anthropic-ai/sdk >= 0.20.0 as an optional peer dependency (npm install @anthropic-ai/sdk).
+import { WorkflowError } from '@sensigo/realm';
+import { ToolCapableLlmProvider } from './llm-provider.js';
+import { sanitizeError, serializeToolResult, parseNamespacedId, tryParseJson, validateSchema, rejectAfter, buildSystemPrompt, } from './agent-utils.js';
+/**
+ * Returns the maximum output tokens for the given Anthropic model.
+ * The Anthropic Messages API requires max_tokens — this must always produce a valid value.
+ * Source: https://docs.anthropic.com/en/docs/about-claude/models/all-models
+ */
+function resolveMaxTokens(model) {
+    // claude-3.5 and claude-4 families support 8192 output tokens.
+    // Matches: claude-3-5-*, claude-3.5-*, claude-<name>-4-*, etc.
+    if (/claude-(3[-.]5|[a-z]+-4)/i.test(model))
+        return 8192;
+    return 4096; // safe fallback for claude-3 and any unrecognised model
+}
+/**
+ * Anthropic LLM provider for realm agent.
+ * Uses the Messages API and extracts JSON from the first text content block.
+ * Retries once if the model returns non-JSON content.
+ */
+export class AnthropicProvider extends ToolCapableLlmProvider {
+    model;
+    constructor(model) {
+        super();
+        this.model = model;
+    }
+    async callStep(prompt, inputSchema) {
+        // Dynamically import @anthropic-ai/sdk to keep it an optional peer dependency.
+        // See openai-provider.ts for an explanation of the 'string' cast technique.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let mod;
+        try {
+            const moduleId = '@anthropic-ai/sdk';
+            mod = await import(moduleId);
+        }
+        catch {
+            console.error('realm agent requires the @anthropic-ai/sdk package. Run: npm install @anthropic-ai/sdk');
+            process.exit(1);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const client = new mod.default({
+            apiKey: process.env['ANTHROPIC_API_KEY'],
+        });
+        const systemPrompt = buildSystemPrompt(inputSchema);
+        const makeRequest = async (userContent) => {
+            const response = await // eslint-disable-next-line @typescript-eslint/no-explicit-any
+             client.messages.create({
+                model: this.model,
+                max_tokens: resolveMaxTokens(this.model),
+                system: systemPrompt,
+                messages: [{ role: 'user', content: userContent }],
+            });
+            const block = response.content.find(
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (b) => b.type === 'text');
+            return block?.text ?? '';
+        };
+        const content = await makeRequest(prompt);
+        try {
+            return JSON.parse(content);
+        }
+        catch {
+            // Retry once with an explicit reminder to return JSON.
+            const retryPrompt = `${prompt}\n\nYour previous response was not valid JSON. Respond with a JSON object only.`;
+            const retry = await makeRequest(retryPrompt);
+            try {
+                return JSON.parse(retry);
+            }
+            catch {
+                throw new Error(`Anthropic returned non-JSON content after retry: ${retry.slice(0, 200)}`);
+            }
+        }
+    }
+    /**
+     * Agentic loop for tool-capable steps. Executes tool calls serially (V1 constraint).
+     * All tool results for one turn are accumulated into a single user message with an array
+     * of tool_result blocks — the Anthropic API rejects interleaved assistant/user turns.
+     */
+    async callStepWithTools(prompt, tools, executor, options) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let mod;
+        try {
+            const moduleId = '@anthropic-ai/sdk';
+            mod = await import(moduleId);
+        }
+        catch {
+            console.error('realm agent requires the @anthropic-ai/sdk package. Run: npm install @anthropic-ai/sdk');
+            process.exit(1);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const client = new mod.default({
+            apiKey: process.env['ANTHROPIC_API_KEY'],
+        });
+        // toolIdMap: bareName → namespaced id, used to recover routing key from LLM responses.
+        // Collision guard: two MCP servers may not expose the same bare tool name in the same step.
+        const toolIdMap = new Map();
+        const anthropicTools = [];
+        for (const tool of tools) {
+            if (toolIdMap.has(tool.name)) {
+                throw new Error(`invariant: duplicate bare tool name '${tool.name}' in toolIdMap — this should have been caught at toolDefs assembly in run-agent.ts`);
+            }
+            toolIdMap.set(tool.name, tool.id);
+            anthropicTools.push({
+                name: tool.name,
+                description: tool.description,
+                input_schema: tool.inputSchema, // note: input_schema, not parameters
+            });
+        }
+        const maxCalls = options.maxToolCalls ?? 20;
+        let tool_call_count = 0;
+        const tool_call_records = [];
+        const system = buildSystemPrompt(options.inputSchema);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const history = [{ role: 'user', content: prompt }];
+        const buildMainCallOpts = () => {
+            const opts = {
+                model: this.model,
+                max_tokens: resolveMaxTokens(this.model),
+                system,
+                messages: history,
+            };
+            if (anthropicTools.length > 0)
+                opts['tools'] = anthropicTools;
+            return opts;
+        };
+        // Calls the API with tool_choice: none and no tools array to force a plain text answer.
+        // Does NOT push to history — callers must ensure history ends with a valid user turn.
+        const performFinalExtraction = async () => {
+            const final = await // eslint-disable-next-line @typescript-eslint/no-explicit-any
+             client.messages.create({
+                model: this.model,
+                max_tokens: resolveMaxTokens(this.model),
+                system,
+                messages: history,
+                tool_choice: { type: 'none' },
+                // NO tools array — enforces text-only response
+                // NO response_format — not a valid Anthropic parameter
+            });
+            const textBlock = final.content.find((b) => b.type === 'text');
+            const text = textBlock?.text ?? '';
+            const parsed = tryParseJson(text);
+            if (parsed && validateSchema(parsed, options.inputSchema)) {
+                return { output: parsed, toolCalls: tool_call_records };
+            }
+            throw new WorkflowError('max_tool_calls reached; final extraction failed', {
+                code: 'ENGINE_STEP_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: false,
+            });
+        };
+        while (true) {
+            const response = await // eslint-disable-next-line @typescript-eslint/no-explicit-any
+             client.messages.create(buildMainCallOpts());
+            const toolUseBlocks = response.content.filter((b) => b.type === 'tool_use');
+            if (toolUseBlocks.length > 0) {
+                history.push({ role: 'assistant', content: response.content });
+                const anthropic_result_blocks = [];
+                let budget_exhausted_mid_batch = false;
+                for (const block of toolUseBlocks) {
+                    const llmToolCallId = block.id; // captured verbatim — "toolu_01abc..."
+                    if (tool_call_count >= maxCalls) {
+                        // Budget exhausted — must still answer every id in the assistant message.
+                        anthropic_result_blocks.push({
+                            type: 'tool_result',
+                            tool_use_id: llmToolCallId,
+                            content: 'Error: tool call budget exhausted',
+                        });
+                        budget_exhausted_mid_batch = true;
+                        continue;
+                    }
+                    const originalId = toolIdMap.get(block.name);
+                    const { serverId, toolName } = parseNamespacedId(originalId);
+                    const args = (block.input ?? {});
+                    const start = Date.now();
+                    let resultContent;
+                    let record;
+                    try {
+                        const rawResult = await Promise.race([
+                            executor(originalId, args),
+                            rejectAfter(options.toolTimeoutMs ?? 30000),
+                        ]);
+                        const serialized = serializeToolResult(rawResult);
+                        record = {
+                            server_id: serverId,
+                            tool: toolName,
+                            args,
+                            result: serialized,
+                            duration_ms: Date.now() - start,
+                        };
+                        resultContent = serialized;
+                    }
+                    catch (err) {
+                        const sanitized = sanitizeError(err);
+                        const content = sanitized.length > 0 ? `Error: ${sanitized}` : 'Error: (redacted)';
+                        record = {
+                            server_id: serverId,
+                            tool: toolName,
+                            args,
+                            result: null,
+                            duration_ms: Date.now() - start,
+                            error: sanitized,
+                        };
+                        resultContent = content;
+                    }
+                    tool_call_records.push(record);
+                    tool_call_count++;
+                    anthropic_result_blocks.push({
+                        type: 'tool_result',
+                        tool_use_id: llmToolCallId,
+                        content: resultContent,
+                    });
+                }
+                const exhausted = budget_exhausted_mid_batch || tool_call_count >= maxCalls;
+                if (exhausted) {
+                    // Merge tool results and extraction prompt into a single user message to avoid
+                    // consecutive user messages, which the Anthropic API rejects with 400.
+                    history.push({
+                        role: 'user',
+                        content: [
+                            ...anthropic_result_blocks,
+                            {
+                                type: 'text',
+                                text: 'You have reached the maximum number of tool calls. Produce your final JSON answer now using only what you have already gathered. No further tool calls will be executed.',
+                            },
+                        ],
+                    });
+                    return performFinalExtraction();
+                }
+                // Normal continuation — single user message with all tool_result blocks.
+                history.push({ role: 'user', content: anthropic_result_blocks });
+            }
+            else {
+                // No tool calls — attempt to parse the final answer.
+                const textBlock = response.content.find((b) => b.type === 'text');
+                const text = textBlock?.text ?? '';
+                const parsed = tryParseJson(text);
+                if (parsed && validateSchema(parsed, options.inputSchema)) {
+                    return { output: parsed, toolCalls: tool_call_records };
+                }
+                // Schema mismatch — append correction and keep looping.
+                history.push({ role: 'assistant', content: response.content });
+                history.push({
+                    role: 'user',
+                    content: 'Your response did not match the required JSON schema. Try again.',
+                });
+                tool_call_count++; // schema correction consumes a slot
+                if (tool_call_count >= maxCalls) {
+                    return performFinalExtraction();
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=anthropic-provider.js.map

package/dist/agent/providers/anthropic-provider.js.map

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

package/dist/agent/providers/llm-provider.d.ts

@@ -0,0 +1,46 @@
+import type { ToolDefinition, ToolExecutor, StepWithToolsResult } from '../mcp/mcp-extensions.js';
+/**
+ * Describes the optional feature set that an LLM provider supports.
+ * Custom providers can override {@link LlmProvider.capabilities} to declare
+ * features beyond the universal baseline.
+ */
+export interface ProviderCapabilities {
+    /**
+     * Whether this provider sends `response_format: { type: 'json_object' }` in API requests.
+     * When false, JSON compliance is enforced through system prompt instruction and retry only.
+     * This is the universal baseline — all providers work without json_object mode.
+     */
+    jsonMode: boolean;
+}
+/**
+ * Abstract base class for LLM providers used by realm agent.
+ * Extend this class to implement a custom provider.
+ */
+export declare abstract class LlmProvider {
+    /** Call the LLM with a step prompt and return a JSON object. */
+    abstract callStep(prompt: string, inputSchema?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Returns the capability set for this provider instance. */
+    capabilities(): ProviderCapabilities;
+}
+/**
+ * Extended abstract class for providers that support the agentic tool-calling loop.
+ * Extend this class if your provider can drive tool-enabled workflow steps.
+ */
+export declare abstract class ToolCapableLlmProvider extends LlmProvider {
+    abstract callStepWithTools(prompt: string, tools: ToolDefinition[], executor: ToolExecutor, options: {
+        inputSchema?: Record<string, unknown>;
+        maxToolCalls?: number;
+        toolTimeoutMs?: number;
+    }): Promise<StepWithToolsResult>;
+}
+/**
+ * Returns true if the provider supports the agentic tool-calling loop.
+ */
+export declare function isToolCapable(provider: LlmProvider): provider is ToolCapableLlmProvider;
+export type ProviderName = 'openai' | 'anthropic';
+/**
+ * Resolves the correct LLM provider from environment and CLI flags.
+ * Throws if no API key is found or the specified package is not installed.
+ */
+export declare function resolveProvider(providerFlag: ProviderName | undefined, modelFlag: string | undefined, baseUrlFlag?: string): Promise<LlmProvider>;
+//# sourceMappingURL=llm-provider.d.ts.map

package/dist/agent/providers/llm-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-provider.d.ts","sourceRoot":"","sources":["../../../src/agent/providers/llm-provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAElG;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,8BAAsB,WAAW;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CACf,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC,6DAA6D;IAC7D,YAAY,IAAI,oBAAoB;CAGrC;AAED;;;GAGG;AACH,8BAAsB,sBAAuB,SAAQ,WAAW;IAC9D,QAAQ,CAAC,iBAAiB,CACxB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,cAAc,EAAE,EACvB,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE;QACP,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACtC,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GACA,OAAO,CAAC,mBAAmB,CAAC;CAChC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,IAAI,sBAAsB,CAEvF;AAED,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAC;AAElD;;;GAGG;AACH,wBAAsB,eAAe,CACnC,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,WAAW,CAAC,CAmCtB"}

package/dist/agent/providers/llm-provider.js

@@ -0,0 +1,56 @@
+/**
+ * Abstract base class for LLM providers used by realm agent.
+ * Extend this class to implement a custom provider.
+ */
+export class LlmProvider {
+    /** Returns the capability set for this provider instance. */
+    capabilities() {
+        return { jsonMode: false };
+    }
+}
+/**
+ * Extended abstract class for providers that support the agentic tool-calling loop.
+ * Extend this class if your provider can drive tool-enabled workflow steps.
+ */
+export class ToolCapableLlmProvider extends LlmProvider {
+}
+/**
+ * Returns true if the provider supports the agentic tool-calling loop.
+ */
+export function isToolCapable(provider) {
+    return provider instanceof ToolCapableLlmProvider;
+}
+/**
+ * Resolves the correct LLM provider from environment and CLI flags.
+ * Throws if no API key is found or the specified package is not installed.
+ */
+export async function resolveProvider(providerFlag, modelFlag, baseUrlFlag) {
+    const hasOpenAI = process.env['OPENAI_API_KEY'] !== undefined;
+    const hasAnthropic = process.env['ANTHROPIC_API_KEY'] !== undefined;
+    if (!hasOpenAI && !hasAnthropic) {
+        throw new Error('realm agent requires an LLM API key. Set OPENAI_API_KEY or ANTHROPIC_API_KEY.');
+    }
+    const provider = providerFlag ?? (hasOpenAI ? 'openai' : 'anthropic');
+    if (baseUrlFlag !== undefined && provider === 'anthropic') {
+        throw new Error('--base-url is only supported with --provider openai (or OpenAI-compatible endpoints). ' +
+            'For Anthropic, configure the endpoint via the ANTHROPIC_BASE_URL environment variable.');
+    }
+    if (provider === 'openai') {
+        // Match o1, o1-mini, o1-preview — the o1 generation requires the special-case
+        // provider (no tool support, system prompt folded into user message).
+        // o3, o3-mini, and o4-mini support the standard Chat Completions API including
+        // function calling, so they route to OpenAIProvider.
+        const REASONING_MODELS = /^o1(-|$)/i;
+        if (modelFlag !== undefined && REASONING_MODELS.test(modelFlag)) {
+            const { OpenAIReasoningProvider } = await import('./openai-reasoning-provider.js');
+            return new OpenAIReasoningProvider(modelFlag);
+        }
+        const { OpenAIProvider } = await import('./openai-provider.js');
+        return new OpenAIProvider(modelFlag ?? 'gpt-4o', baseUrlFlag);
+    }
+    else {
+        const { AnthropicProvider } = await import('./anthropic-provider.js');
+        return new AnthropicProvider(modelFlag ?? 'claude-sonnet-4-5');
+    }
+}
+//# sourceMappingURL=llm-provider.js.map

package/dist/agent/providers/llm-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-provider.js","sourceRoot":"","sources":["../../../src/agent/providers/llm-provider.ts"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,MAAM,OAAgB,WAAW;IAO/B,6DAA6D;IAC7D,YAAY;QACV,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC7B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAgB,sBAAuB,SAAQ,WAAW;CAW/D;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,QAAqB;IACjD,OAAO,QAAQ,YAAY,sBAAsB,CAAC;AACpD,CAAC;AAID;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,YAAsC,EACtC,SAA6B,EAC7B,WAAoB;IAEpB,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,KAAK,SAAS,CAAC;IAC9D,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,KAAK,SAAS,CAAC;IAEpE,IAAI,CAAC,SAAS,IAAI,CAAC,YAAY,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,+EAA+E,CAChF,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,YAAY,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IAEtE,IAAI,WAAW,KAAK,SAAS,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CACb,wFAAwF;YACtF,wFAAwF,CAC3F,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,8EAA8E;QAC9E,sEAAsE;QACtE,+EAA+E;QAC/E,qDAAqD;QACrD,MAAM,gBAAgB,GAAG,WAAW,CAAC;QACrC,IAAI,SAAS,KAAK,SAAS,IAAI,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAChE,MAAM,EAAE,uBAAuB,EAAE,GAAG,MAAM,MAAM,CAAC,gCAAgC,CAAC,CAAC;YACnF,OAAO,IAAI,uBAAuB,CAAC,SAAS,CAAC,CAAC;QAChD,CAAC;QACD,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;QAChE,OAAO,IAAI,cAAc,CAAC,SAAS,IAAI,QAAQ,EAAE,WAAW,CAAC,CAAC;IAChE,CAAC;SAAM,CAAC;QACN,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;QACtE,OAAO,IAAI,iBAAiB,CAAC,SAAS,IAAI,mBAAmB,CAAC,CAAC;IACjE,CAAC;AACH,CAAC"}

package/dist/agent/providers/openai-provider.d.ts

@@ -0,0 +1,30 @@
+import { ToolCapableLlmProvider, type ProviderCapabilities } from './llm-provider.js';
+import type { ToolDefinition, ToolExecutor, StepWithToolsResult } from '../mcp/mcp-extensions.js';
+/**
+ * OpenAI LLM provider for realm agent.
+ * Uses the Chat Completions API. Sends `response_format: json_object` on native
+ * OpenAI endpoints; falls back to prompt-only JSON enforcement on compat endpoints
+ * behind `--base-url`. Retries once if the model returns non-JSON content.
+ */
+export declare class OpenAIProvider extends ToolCapableLlmProvider {
+    private readonly model;
+    private readonly baseUrl;
+    constructor(model: string, baseUrl?: string);
+    /**
+     * Native OpenAI endpoints have a well-defined, tested capability surface that includes
+     * json_object mode. Custom compat endpoints behind --base-url do not guarantee this feature.
+     * Default to prompt-only enforcement for any unknown endpoint.
+     */
+    capabilities(): ProviderCapabilities;
+    callStep(prompt: string, inputSchema?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Agentic loop for tool-capable steps. Executes tool calls serially (V1 constraint)
+     * until the model returns a final JSON answer or the tool call budget is exhausted.
+     */
+    callStepWithTools(prompt: string, tools: ToolDefinition[], executor: ToolExecutor, options: {
+        inputSchema?: Record<string, unknown>;
+        maxToolCalls?: number;
+        toolTimeoutMs?: number;
+    }): Promise<StepWithToolsResult>;
+}
+//# sourceMappingURL=openai-provider.d.ts.map

package/dist/agent/providers/openai-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-provider.d.ts","sourceRoot":"","sources":["../../../src/agent/providers/openai-provider.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,sBAAsB,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACtF,OAAO,KAAK,EAEV,cAAc,EACd,YAAY,EACZ,mBAAmB,EACpB,MAAM,0BAA0B,CAAC;AAWlC;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,sBAAsB;IACxD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAEjC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;IAM3C;;;;OAIG;IACH,YAAY,IAAI,oBAAoB;IAI9B,QAAQ,CACZ,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IA8DnC;;;OAGG;IACG,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,cAAc,EAAE,EACvB,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE;QACP,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACtC,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GACA,OAAO,CAAC,mBAAmB,CAAC;CAyLhC"}