@framers/agentos 0.1.94 → 0.1.96

package/dist/emergent/ForgeToolMetaTool.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview ForgeToolMetaTool — ITool implementation that agents call to
+ * create new tools at runtime via the Emergent Capability Engine.
+ *
+ * @module @framers/agentos/emergent/ForgeToolMetaTool
+ *
+ * This is the meta-tool that bridges the LLM tool-call interface with the
+ * {@link EmergentCapabilityEngine}. When an agent determines that no existing
+ * capability matches its need, it calls `forge_tool` with a name, description,
+ * schemas, implementation (compose or sandbox), and test cases.
+ *
+ * Only registered when the agent is configured with `emergent: true`.
+ * Adds ~120 tokens to the tool list.
+ */
+import type { ITool, ToolExecutionResult, ToolExecutionContext, JSONSchemaObject } from '../core/tools/ITool.js';
+import type { ForgeResult } from './types.js';
+import type { EmergentCapabilityEngine } from './EmergentCapabilityEngine.js';
+/**
+ * Input arguments accepted by the `forge_tool` meta-tool.
+ *
+ * Mirrors {@link ForgeToolRequest} but typed as a `Record<string, any>` to
+ * satisfy the {@link ITool} generic constraint while retaining semantic clarity.
+ */
+export interface ForgeToolInput extends Record<string, any> {
+    /** Machine-readable name for the new tool. */
+    name: string;
+    /** Natural language description of the tool's purpose. */
+    description: string;
+    /** JSON Schema for the tool's input arguments. */
+    inputSchema: JSONSchemaObject;
+    /** JSON Schema for the tool's expected output (optional). */
+    outputSchema?: JSONSchemaObject;
+    /**
+     * Implementation specification — either compose (chain existing tools) or
+     * sandbox (arbitrary code). Discriminated on the `mode` field.
+     */
+    implementation: {
+        mode: 'compose';
+        steps: Array<{
+            name: string;
+            tool: string;
+            inputMapping: Record<string, unknown>;
+        }>;
+    } | {
+        mode: 'sandbox';
+        code: string;
+        allowlist: string[];
+    };
+    /**
+     * One or more test cases for the judge to evaluate.
+     * Each has an `input` object and optional `expectedOutput`.
+     */
+    testCases: Array<{
+        input: Record<string, unknown>;
+        expectedOutput?: unknown;
+    }>;
+}
+/**
+ * Meta-tool enabling agents to create new tools at runtime.
+ *
+ * Only registered when the agent is configured with `emergent: true`.
+ * Adds ~120 tokens to the tool list. Agents provide: name, description,
+ * schemas, implementation (compose existing tools or write sandboxed code),
+ * and test cases.
+ *
+ * @example
+ * ```ts
+ * const metaTool = new ForgeToolMetaTool(engine);
+ * // Register with ToolOrchestrator:
+ * orchestrator.registerTool(metaTool);
+ *
+ * // Agent calls via tool-call interface:
+ * const result = await metaTool.execute({
+ *   name: 'add_numbers',
+ *   description: 'Add two numbers together.',
+ *   inputSchema: { type: 'object', properties: { a: { type: 'number' }, b: { type: 'number' } } },
+ *   outputSchema: { type: 'object', properties: { sum: { type: 'number' } } },
+ *   implementation: {
+ *     mode: 'sandbox',
+ *     code: 'function execute(input) { return { sum: input.a + input.b }; }',
+ *     allowlist: [],
+ *   },
+ *   testCases: [{ input: { a: 2, b: 3 }, expectedOutput: { sum: 5 } }],
+ * }, context);
+ * ```
+ */
+export declare class ForgeToolMetaTool implements ITool<ForgeToolInput, ForgeResult> {
+    /** @inheritdoc */
+    readonly id = "com.framers.emergent.forge-tool";
+    /** @inheritdoc */
+    readonly name = "forge_tool";
+    /** @inheritdoc */
+    readonly displayName = "Forge Tool";
+    /** @inheritdoc */
+    readonly description: string;
+    /** @inheritdoc */
+    readonly category = "emergent";
+    /** @inheritdoc */
+    readonly hasSideEffects = true;
+    /** @inheritdoc */
+    readonly inputSchema: JSONSchemaObject;
+    /** Reference to the engine that orchestrates the forge pipeline. */
+    private readonly engine;
+    /**
+     * Create a new ForgeToolMetaTool.
+     *
+     * @param engine - The {@link EmergentCapabilityEngine} that will handle the
+     *   actual forge pipeline (build → test → judge → register).
+     */
+    constructor(engine: EmergentCapabilityEngine);
+    /**
+     * Execute the forge pipeline via the engine.
+     *
+     * Extracts the agent ID and session/correlation ID from the execution context
+     * and delegates to {@link EmergentCapabilityEngine.forge}.
+     *
+     * @param args - The forge tool input arguments (name, description, schemas,
+     *   implementation, test cases).
+     * @param context - The tool execution context providing agent and session IDs.
+     * @returns A {@link ToolExecutionResult} wrapping the {@link ForgeResult}.
+     */
+    execute(args: ForgeToolInput, context: ToolExecutionContext): Promise<ToolExecutionResult<ForgeResult>>;
+}
+//# sourceMappingURL=ForgeToolMetaTool.d.ts.map

package/dist/emergent/ForgeToolMetaTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ForgeToolMetaTool.d.ts","sourceRoot":"","sources":["../../src/emergent/ForgeToolMetaTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,KAAK,EACL,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAoB,WAAW,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAM9E;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IACzD,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IAEb,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IAEpB,kDAAkD;IAClD,WAAW,EAAE,gBAAgB,CAAC;IAE9B,6DAA6D;IAC7D,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAEhC;;;OAGG;IACH,cAAc,EACV;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,CAAC,CAAA;KAAE,GACxG;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAE3D;;;OAGG;IACH,SAAS,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAChF;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,iBAAkB,YAAW,KAAK,CAAC,cAAc,EAAE,WAAW,CAAC;IAC1E,kBAAkB;IAClB,QAAQ,CAAC,EAAE,qCAAqC;IAEhD,kBAAkB;IAClB,QAAQ,CAAC,IAAI,gBAAgB;IAE7B,kBAAkB;IAClB,QAAQ,CAAC,WAAW,gBAAgB;IAEpC,kBAAkB;IAClB,QAAQ,CAAC,WAAW,SAGuB;IAE3C,kBAAkB;IAClB,QAAQ,CAAC,QAAQ,cAAc;IAE/B,kBAAkB;IAClB,QAAQ,CAAC,cAAc,QAAQ;IAE/B,kBAAkB;IAClB,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAwEpC;IAEF,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAElD;;;;;OAKG;gBACS,MAAM,EAAE,wBAAwB;IAQ5C;;;;;;;;;;OAUG;IACG,OAAO,CACX,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC;CAY7C"}

package/dist/emergent/ForgeToolMetaTool.js

@@ -0,0 +1,170 @@
+/**
+ * @fileoverview ForgeToolMetaTool — ITool implementation that agents call to
+ * create new tools at runtime via the Emergent Capability Engine.
+ *
+ * @module @framers/agentos/emergent/ForgeToolMetaTool
+ *
+ * This is the meta-tool that bridges the LLM tool-call interface with the
+ * {@link EmergentCapabilityEngine}. When an agent determines that no existing
+ * capability matches its need, it calls `forge_tool` with a name, description,
+ * schemas, implementation (compose or sandbox), and test cases.
+ *
+ * Only registered when the agent is configured with `emergent: true`.
+ * Adds ~120 tokens to the tool list.
+ */
+// ============================================================================
+// META-TOOL
+// ============================================================================
+/**
+ * Meta-tool enabling agents to create new tools at runtime.
+ *
+ * Only registered when the agent is configured with `emergent: true`.
+ * Adds ~120 tokens to the tool list. Agents provide: name, description,
+ * schemas, implementation (compose existing tools or write sandboxed code),
+ * and test cases.
+ *
+ * @example
+ * ```ts
+ * const metaTool = new ForgeToolMetaTool(engine);
+ * // Register with ToolOrchestrator:
+ * orchestrator.registerTool(metaTool);
+ *
+ * // Agent calls via tool-call interface:
+ * const result = await metaTool.execute({
+ *   name: 'add_numbers',
+ *   description: 'Add two numbers together.',
+ *   inputSchema: { type: 'object', properties: { a: { type: 'number' }, b: { type: 'number' } } },
+ *   outputSchema: { type: 'object', properties: { sum: { type: 'number' } } },
+ *   implementation: {
+ *     mode: 'sandbox',
+ *     code: 'function execute(input) { return { sum: input.a + input.b }; }',
+ *     allowlist: [],
+ *   },
+ *   testCases: [{ input: { a: 2, b: 3 }, expectedOutput: { sum: 5 } }],
+ * }, context);
+ * ```
+ */
+export class ForgeToolMetaTool {
+    /**
+     * Create a new ForgeToolMetaTool.
+     *
+     * @param engine - The {@link EmergentCapabilityEngine} that will handle the
+     *   actual forge pipeline (build → test → judge → register).
+     */
+    constructor(engine) {
+        /** @inheritdoc */
+        this.id = 'com.framers.emergent.forge-tool';
+        /** @inheritdoc */
+        this.name = 'forge_tool';
+        /** @inheritdoc */
+        this.displayName = 'Forge Tool';
+        /** @inheritdoc */
+        this.description = 'Create a new tool when no existing capability matches your need. ' +
+            'Provide a name, description, implementation (compose existing tools or ' +
+            'write sandboxed code), and test cases.';
+        /** @inheritdoc */
+        this.category = 'emergent';
+        /** @inheritdoc */
+        this.hasSideEffects = true;
+        /** @inheritdoc */
+        this.inputSchema = {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Machine-readable name for the new tool.',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Natural language description of what the tool does.',
+                },
+                inputSchema: {
+                    type: 'object',
+                    description: 'JSON Schema for the tool input arguments.',
+                },
+                outputSchema: {
+                    type: 'object',
+                    description: 'JSON Schema for the tool output (optional).',
+                },
+                implementation: {
+                    description: 'Implementation: compose existing tools or write sandboxed code.',
+                    oneOf: [
+                        {
+                            type: 'object',
+                            properties: {
+                                mode: { type: 'string', const: 'compose' },
+                                steps: {
+                                    type: 'array',
+                                    items: {
+                                        type: 'object',
+                                        properties: {
+                                            name: { type: 'string' },
+                                            tool: { type: 'string' },
+                                            inputMapping: { type: 'object' },
+                                        },
+                                        required: ['name', 'tool', 'inputMapping'],
+                                    },
+                                    minItems: 1,
+                                },
+                            },
+                            required: ['mode', 'steps'],
+                        },
+                        {
+                            type: 'object',
+                            properties: {
+                                mode: { type: 'string', const: 'sandbox' },
+                                code: { type: 'string' },
+                                allowlist: {
+                                    type: 'array',
+                                    items: { type: 'string', enum: ['fetch', 'fs.readFile', 'crypto'] },
+                                },
+                            },
+                            required: ['mode', 'code', 'allowlist'],
+                        },
+                    ],
+                },
+                testCases: {
+                    type: 'array',
+                    description: 'One or more test cases for the judge to evaluate.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            input: { type: 'object' },
+                            expectedOutput: {},
+                        },
+                        required: ['input'],
+                    },
+                    minItems: 1,
+                },
+            },
+            required: ['name', 'description', 'inputSchema', 'implementation', 'testCases'],
+        };
+        this.engine = engine;
+    }
+    // --------------------------------------------------------------------------
+    // EXECUTE
+    // --------------------------------------------------------------------------
+    /**
+     * Execute the forge pipeline via the engine.
+     *
+     * Extracts the agent ID and session/correlation ID from the execution context
+     * and delegates to {@link EmergentCapabilityEngine.forge}.
+     *
+     * @param args - The forge tool input arguments (name, description, schemas,
+     *   implementation, test cases).
+     * @param context - The tool execution context providing agent and session IDs.
+     * @returns A {@link ToolExecutionResult} wrapping the {@link ForgeResult}.
+     */
+    async execute(args, context) {
+        const result = await this.engine.forge(args, {
+            agentId: context.gmiId || 'unknown',
+            sessionId: context.correlationId || 'unknown',
+        });
+        return {
+            success: result.success,
+            output: result,
+            error: result.error,
+        };
+    }
+}
+//# sourceMappingURL=ForgeToolMetaTool.js.map

package/dist/emergent/ForgeToolMetaTool.js.map

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

package/dist/emergent/SandboxedToolForge.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @fileoverview SandboxedToolForge — runs agent-generated JavaScript code in an
+ * isolated sandbox with strict resource limits and API allowlisting.
+ *
+ * @module @framers/agentos/emergent/SandboxedToolForge
+ *
+ * Overview:
+ * - Attempts to use `isolated-vm` for true V8 isolate sandboxing when available.
+ * - Falls back to Node.js `vm` module with timeout when `isolated-vm` is not installed.
+ * - Enforces configurable memory limits (default 128 MB), execution timeouts (default 5 s),
+ *   and a strict API blocklist that prevents access to `eval`, `Function`, `process`,
+ *   `require`, `import`, `child_process`, and `fs.write*`.
+ *
+ * Allowlisted APIs (each requires explicit opt-in via {@link SandboxAPI}):
+ * - `fetch` — HTTP requests (domain-restricted via {@link SandboxedToolForgeConfig.fetchDomainAllowlist}).
+ * - `fs.readFile` — Read-only file access (path-restricted, max 1 MB).
+ * - `crypto` — Hashing and HMAC only (`createHash`, `createHmac`).
+ *
+ * Security model:
+ * 1. **Static validation** ({@link validateCode}) rejects dangerous patterns
+ *    (regex scan) before any code reaches the runtime.
+ * 2. **Runtime isolation** executes validated code inside a minimal context that
+ *    exposes only JSON, Math, Date, TextEncoder, TextDecoder, and explicitly
+ *    opted-in APIs.
+ * 3. **Resource bounding** enforces wall-clock timeout so runaway loops cannot
+ *    starve the host process.
+ */
+import type { SandboxExecutionRequest, SandboxExecutionResult, SandboxAPI } from './types.js';
+/**
+ * Configuration options for the {@link SandboxedToolForge}.
+ *
+ * All fields are optional and fall back to sensible defaults.
+ */
+export interface SandboxedToolForgeConfig {
+    /**
+     * Maximum heap memory in megabytes for the sandbox process.
+     * Used with `isolated-vm`; the `vm` fallback cannot enforce memory limits.
+     * @default 128
+     */
+    memoryMB?: number;
+    /**
+     * Maximum wall-clock execution time in milliseconds.
+     * @default 5000
+     */
+    timeoutMs?: number;
+    /**
+     * When `fetch` is in the allowlist, only requests to these domains are
+     * permitted. An empty array means all domains are allowed.
+     * Domain matching is case-insensitive and checks exact host equality.
+     * @default []
+     */
+    fetchDomainAllowlist?: string[];
+    /**
+     * Filesystem roots sandboxed `fs.readFile` calls may access.
+     * Relative paths are resolved from the current working directory.
+     * Defaults to the current working directory only.
+     */
+    fsReadRoots?: string[];
+}
+/**
+ * Runs agent-generated code in an isolated sandbox with strict resource limits.
+ *
+ * Attempts to use `isolated-vm` for true V8 isolate sandboxing. Falls back to
+ * Node.js `vm` module with timeout if `isolated-vm` is not installed.
+ *
+ * Resource limits:
+ * - Memory: configurable, default 128 MB
+ * - Execution time: configurable, default 5000 ms
+ * - Blocked APIs: eval, Function, process, require, import, child_process, fs.write*
+ *
+ * Allowlisted APIs (each requires explicit opt-in):
+ * - `fetch`: HTTP requests (domain-restricted)
+ * - `fs.readFile`: Read-only file access (path-restricted, max 1 MB)
+ * - `crypto`: Hashing and HMAC only
+ *
+ * @example
+ * ```ts
+ * const forge = new SandboxedToolForge({ timeoutMs: 3000 });
+ *
+ * const result = await forge.execute({
+ *   code: 'function execute(input) { return input.a + input.b; }',
+ *   input: { a: 2, b: 3 },
+ *   allowlist: [],
+ *   memoryMB: 128,
+ *   timeoutMs: 3000,
+ * });
+ *
+ * console.log(result.output); // 5
+ * ```
+ */
+export declare class SandboxedToolForge {
+    /** Resolved memory limit in MB. */
+    private readonly memoryMB;
+    /** Resolved timeout in milliseconds. */
+    private readonly timeoutMs;
+    /** Domain allowlist for sandboxed `fetch` calls. */
+    private readonly fetchDomainAllowlist;
+    /** Filesystem roots sandboxed reads may access. */
+    private readonly fsReadRoots;
+    /**
+     * Create a new SandboxedToolForge instance.
+     *
+     * @param config - Optional configuration overrides. All fields have sensible
+     *   defaults (128 MB memory, 5000 ms timeout, no domain restrictions).
+     */
+    constructor(config?: SandboxedToolForgeConfig);
+    /**
+     * Static analysis of code — reject dangerous patterns before execution.
+     *
+     * Scans the source string for banned API usage patterns using regex matching.
+     * If an API is not present in the allowlist, references to it are also flagged.
+     *
+     * Checked patterns (always banned):
+     * - `eval()`, `new Function()`, `require()`, `import`, `process.*`
+     * - `child_process`, `fs.write*`, `fs.unlink`, `fs.rm`, `fs.rmdir`
+     *
+     * Conditionally banned (when not in allowlist):
+     * - `fetch(` — when `'fetch'` is not in the allowlist
+     * - `fs.*` — when `'fs.readFile'` is not in the allowlist
+     * - `crypto.*` — when `'crypto'` is not in the allowlist
+     *
+     * @param code - The raw source code string to validate.
+     * @param allowlist - The set of APIs the code is permitted to use.
+     * @returns An object with `valid: true` if no violations were found, or
+     *   `valid: false` with a `violations` array describing each flagged pattern.
+     *
+     * @example
+     * ```ts
+     * const forge = new SandboxedToolForge();
+     * const result = forge.validateCode('eval("exploit")', []);
+     * // result.valid === false
+     * // result.violations === ['eval() is forbidden']
+     * ```
+     */
+    validateCode(code: string, allowlist: SandboxAPI[]): {
+        valid: boolean;
+        violations: string[];
+    };
+    /**
+     * Execute agent-generated code in the sandbox.
+     *
+     * The code must define a function named `execute` that accepts a single
+     * argument and returns the output:
+     *
+     * ```js
+     * function execute(input) { return input.a + input.b; }
+     * ```
+     *
+     * Execution flow:
+     * 1. Run {@link validateCode} — reject immediately if violations are found.
+     * 2. Wrap the agent's code into a self-contained expression that calls `execute`.
+     * 3. Run in a Node.js `vm` sandbox with a restricted global context.
+     * 4. Parse the output, measure execution time, and return the result.
+     *
+     * @param request - The execution request containing code, input, allowlist,
+     *   and resource limits.
+     * @returns A {@link SandboxExecutionResult} with the output (on success) or
+     *   error description (on failure), plus execution time telemetry.
+     *
+     * @example
+     * ```ts
+     * const result = await forge.execute({
+     *   code: 'function execute(input) { return { sum: input.a + input.b }; }',
+     *   input: { a: 10, b: 20 },
+     *   allowlist: [],
+     *   memoryMB: 128,
+     *   timeoutMs: 5000,
+     * });
+     * // result.success === true
+     * // result.output === { sum: 30 }
+     * ```
+     */
+    execute(request: SandboxExecutionRequest): Promise<SandboxExecutionResult>;
+    /**
+     * Build the global context object for the VM sandbox.
+     *
+     * Provides a minimal set of safe built-ins (JSON, Math, Date, TextEncoder,
+     * TextDecoder) and conditionally injects allowlisted APIs.
+     *
+     * @param allowlist - The set of APIs to inject into the sandbox.
+     * @returns A plain object suitable for {@link createContext}.
+     */
+    private buildSandboxContext;
+}
+//# sourceMappingURL=SandboxedToolForge.d.ts.map

package/dist/emergent/SandboxedToolForge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxedToolForge.d.ts","sourceRoot":"","sources":["../../src/emergent/SandboxedToolForge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,OAAO,KAAK,EACV,uBAAuB,EACvB,sBAAsB,EACtB,UAAU,EACX,MAAM,YAAY,CAAC;AAMpB;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AA+BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,kBAAkB;IAC7B,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,oDAAoD;IACpD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAW;IAEhD,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;IAEvC;;;;;OAKG;gBACS,MAAM,CAAC,EAAE,wBAAwB;IAe7C;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,YAAY,CACV,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,UAAU,EAAE,GACtB;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE;IAwC3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,OAAO,CACX,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC;IAqGlC;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;CA2G5B"}