@framers/agentos 0.1.121 → 0.1.122

package/dist/emergent/AdaptPersonalityTool.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview AdaptPersonalityTool — ITool implementation that enables agents
+ * to mutate their own HEXACO personality traits at runtime with per-session
+ * budget enforcement.
+ *
+ * @module @framers/agentos/emergent/AdaptPersonalityTool
+ *
+ * Agents call `adapt_personality` to shift a specific trait dimension (e.g.
+ * openness, conscientiousness) by a bounded delta. The tool enforces:
+ * - Only valid HEXACO trait names are accepted.
+ * - Reasoning must be provided for every mutation (audit trail).
+ * - Per-session budgets cap the total absolute delta per trait.
+ * - Values are always clamped to the [0, 1] range.
+ *
+ * All mutations are recorded in the injected {@link PersonalityMutationStore}
+ * for durability and downstream analysis.
+ */
+import type { ITool, ToolExecutionResult, ToolExecutionContext, JSONSchemaObject } from '../core/tools/ITool.js';
+/**
+ * The six HEXACO personality dimensions that agents may self-modify.
+ *
+ * Each trait is a continuous value in the range [0, 1]:
+ * - `openness`          — curiosity, creativity, willingness to explore
+ * - `conscientiousness` — discipline, thoroughness, reliability
+ * - `emotionality`      — emotional reactivity, empathy, anxiety
+ * - `extraversion`      — sociability, energy, assertiveness
+ * - `agreeableness`     — patience, tolerance, cooperation
+ * - `honesty`           — sincerity, fairness, modesty
+ */
+export declare const VALID_TRAITS: readonly ["openness", "conscientiousness", "emotionality", "extraversion", "agreeableness", "honesty"];
+/** Union type of valid HEXACO trait names. */
+export type HEXACOTrait = (typeof VALID_TRAITS)[number];
+/**
+ * A single personality mutation record persisted for audit and analysis.
+ */
+export interface PersonalityMutation {
+    /** The HEXACO trait that was modified. */
+    trait: string;
+    /** The trait value before the mutation. */
+    previousValue: number;
+    /** The trait value after the mutation. */
+    newValue: number;
+    /** The actual delta applied (may differ from requested if clamped). */
+    delta: number;
+    /** Free-text reasoning provided by the agent for this mutation. */
+    reasoning: string;
+    /** ISO-8601 timestamp of when the mutation occurred. */
+    timestamp: string;
+}
+/**
+ * Durable store interface for recording personality mutations.
+ * Implementations may write to SQLite, a JSON file, or in-memory arrays.
+ */
+export interface PersonalityMutationStore {
+    /** Persist a single mutation record. */
+    record(mutation: PersonalityMutation): void;
+}
+/**
+ * Input arguments accepted by the `adapt_personality` tool.
+ */
+export interface AdaptPersonalityInput extends Record<string, any> {
+    /** The HEXACO trait to modify. */
+    trait: string;
+    /** The signed delta to apply (positive = increase, negative = decrease). */
+    delta: number;
+    /** Free-text reasoning explaining why this adaptation is warranted. */
+    reasoning: string;
+}
+/**
+ * Result payload returned after a successful personality adaptation.
+ */
+export interface AdaptPersonalityOutput {
+    /** The trait that was modified. */
+    trait: string;
+    /** Value before the mutation. */
+    previousValue: number;
+    /** Value after the mutation. */
+    newValue: number;
+    /** The actual delta applied. */
+    delta: number;
+    /** Whether the delta was clamped due to budget or range limits. */
+    clamped: boolean;
+    /** Total absolute delta applied to this trait in the current session. */
+    sessionTotal: number;
+    /** Remaining budget for this trait in the current session. */
+    remainingBudget: number;
+}
+/**
+ * Dependencies injected into the {@link AdaptPersonalityTool} constructor.
+ */
+export interface AdaptPersonalityDeps {
+    /** Configuration controlling per-session budget limits. */
+    config: {
+        /** Maximum total |delta| that may be applied to any single trait per session. */
+        maxDeltaPerSession: number;
+    };
+    /** Durable store for recording mutation history. */
+    mutationStore: PersonalityMutationStore;
+    /** Getter returning the current personality trait map (trait → value in [0, 1]). */
+    getPersonality: () => Record<string, number>;
+    /** Setter to apply a new value for a specific trait. */
+    setPersonality: (trait: string, value: number) => void;
+}
+/**
+ * ITool implementation enabling agents to self-modify their HEXACO personality
+ * traits within per-session budgets.
+ *
+ * @example
+ * ```ts
+ * const tool = new AdaptPersonalityTool({
+ *   config: { maxDeltaPerSession: 0.3 },
+ *   mutationStore: myStore,
+ *   getPersonality: () => agent.personality,
+ *   setPersonality: (t, v) => { agent.personality[t] = v; },
+ * });
+ *
+ * const result = await tool.execute(
+ *   { trait: 'openness', delta: 0.1, reasoning: 'User prefers creative responses.' },
+ *   context,
+ * );
+ * ```
+ */
+export declare class AdaptPersonalityTool implements ITool<AdaptPersonalityInput, AdaptPersonalityOutput> {
+    /** @inheritdoc */
+    readonly id = "com.framers.emergent.adapt-personality";
+    /** @inheritdoc */
+    readonly name = "adapt_personality";
+    /** @inheritdoc */
+    readonly displayName = "Adapt Personality";
+    /** @inheritdoc */
+    readonly description: string;
+    /** @inheritdoc */
+    readonly category = "emergent";
+    /** @inheritdoc */
+    readonly hasSideEffects = true;
+    /** @inheritdoc */
+    readonly inputSchema: JSONSchemaObject;
+    /** Per-session accumulated |delta| per trait. Reset on tool construction. */
+    private readonly sessionDeltas;
+    /** Injected dependencies. */
+    private readonly deps;
+    /**
+     * Create a new AdaptPersonalityTool.
+     *
+     * @param deps - Injected dependencies including config, mutation store,
+     *   and personality getter/setter.
+     */
+    constructor(deps: AdaptPersonalityDeps);
+    /**
+     * Apply a personality trait mutation within session budget constraints.
+     *
+     * @param args - The trait, delta, and reasoning for the mutation.
+     * @param _context - Tool execution context (unused but required by ITool).
+     * @returns A {@link ToolExecutionResult} wrapping the mutation outcome.
+     */
+    execute(args: AdaptPersonalityInput, _context: ToolExecutionContext): Promise<ToolExecutionResult<AdaptPersonalityOutput>>;
+}
+//# sourceMappingURL=AdaptPersonalityTool.d.ts.map

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

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

package/dist/emergent/AdaptPersonalityTool.js

@@ -0,0 +1,190 @@
+/**
+ * @fileoverview AdaptPersonalityTool — ITool implementation that enables agents
+ * to mutate their own HEXACO personality traits at runtime with per-session
+ * budget enforcement.
+ *
+ * @module @framers/agentos/emergent/AdaptPersonalityTool
+ *
+ * Agents call `adapt_personality` to shift a specific trait dimension (e.g.
+ * openness, conscientiousness) by a bounded delta. The tool enforces:
+ * - Only valid HEXACO trait names are accepted.
+ * - Reasoning must be provided for every mutation (audit trail).
+ * - Per-session budgets cap the total absolute delta per trait.
+ * - Values are always clamped to the [0, 1] range.
+ *
+ * All mutations are recorded in the injected {@link PersonalityMutationStore}
+ * for durability and downstream analysis.
+ */
+// ============================================================================
+// VALID TRAITS
+// ============================================================================
+/**
+ * The six HEXACO personality dimensions that agents may self-modify.
+ *
+ * Each trait is a continuous value in the range [0, 1]:
+ * - `openness`          — curiosity, creativity, willingness to explore
+ * - `conscientiousness` — discipline, thoroughness, reliability
+ * - `emotionality`      — emotional reactivity, empathy, anxiety
+ * - `extraversion`      — sociability, energy, assertiveness
+ * - `agreeableness`     — patience, tolerance, cooperation
+ * - `honesty`           — sincerity, fairness, modesty
+ */
+export const VALID_TRAITS = [
+    'openness',
+    'conscientiousness',
+    'emotionality',
+    'extraversion',
+    'agreeableness',
+    'honesty',
+];
+// ============================================================================
+// TOOL IMPLEMENTATION
+// ============================================================================
+/**
+ * ITool implementation enabling agents to self-modify their HEXACO personality
+ * traits within per-session budgets.
+ *
+ * @example
+ * ```ts
+ * const tool = new AdaptPersonalityTool({
+ *   config: { maxDeltaPerSession: 0.3 },
+ *   mutationStore: myStore,
+ *   getPersonality: () => agent.personality,
+ *   setPersonality: (t, v) => { agent.personality[t] = v; },
+ * });
+ *
+ * const result = await tool.execute(
+ *   { trait: 'openness', delta: 0.1, reasoning: 'User prefers creative responses.' },
+ *   context,
+ * );
+ * ```
+ */
+export class AdaptPersonalityTool {
+    /**
+     * Create a new AdaptPersonalityTool.
+     *
+     * @param deps - Injected dependencies including config, mutation store,
+     *   and personality getter/setter.
+     */
+    constructor(deps) {
+        /** @inheritdoc */
+        this.id = 'com.framers.emergent.adapt-personality';
+        /** @inheritdoc */
+        this.name = 'adapt_personality';
+        /** @inheritdoc */
+        this.displayName = 'Adapt Personality';
+        /** @inheritdoc */
+        this.description = 'Adjust a HEXACO personality trait by a bounded delta. Requires reasoning ' +
+            'for every mutation. Per-session budgets prevent runaway drift.';
+        /** @inheritdoc */
+        this.category = 'emergent';
+        /** @inheritdoc */
+        this.hasSideEffects = true;
+        /** @inheritdoc */
+        this.inputSchema = {
+            type: 'object',
+            properties: {
+                trait: {
+                    type: 'string',
+                    enum: [...VALID_TRAITS],
+                    description: 'The HEXACO personality trait to modify.',
+                },
+                delta: {
+                    type: 'number',
+                    description: 'Signed delta to apply (positive = increase, negative = decrease).',
+                },
+                reasoning: {
+                    type: 'string',
+                    description: 'Why this personality adaptation is warranted.',
+                },
+            },
+            required: ['trait', 'delta', 'reasoning'],
+        };
+        /** Per-session accumulated |delta| per trait. Reset on tool construction. */
+        this.sessionDeltas = new Map();
+        this.deps = deps;
+    }
+    // --------------------------------------------------------------------------
+    // EXECUTE
+    // --------------------------------------------------------------------------
+    /**
+     * Apply a personality trait mutation within session budget constraints.
+     *
+     * @param args - The trait, delta, and reasoning for the mutation.
+     * @param _context - Tool execution context (unused but required by ITool).
+     * @returns A {@link ToolExecutionResult} wrapping the mutation outcome.
+     */
+    async execute(args, _context) {
+        const { trait, delta, reasoning } = args;
+        // 1. Validate trait name
+        if (!VALID_TRAITS.includes(trait)) {
+            return {
+                success: false,
+                error: `Invalid trait "${trait}". Must be one of: ${VALID_TRAITS.join(', ')}`,
+            };
+        }
+        // 2. Validate reasoning is non-empty
+        if (!reasoning || typeof reasoning !== 'string' || reasoning.trim().length === 0) {
+            return {
+                success: false,
+                error: 'reasoning is required and must be a non-empty string',
+            };
+        }
+        // 3. Check session budget — track total |delta| per trait
+        const { maxDeltaPerSession } = this.deps.config;
+        const currentSessionTotal = this.sessionDeltas.get(trait) ?? 0;
+        const remainingBudget = maxDeltaPerSession - currentSessionTotal;
+        // 4. Clamp delta to remaining budget
+        let effectiveDelta = delta;
+        let clamped = false;
+        if (Math.abs(effectiveDelta) > remainingBudget) {
+            effectiveDelta = remainingBudget * Math.sign(effectiveDelta);
+            clamped = true;
+        }
+        // If no budget remains, the effective delta is 0
+        if (remainingBudget <= 0) {
+            effectiveDelta = 0;
+            clamped = true;
+        }
+        // 5. Get current value, compute new value (clamped 0–1), apply
+        const personality = this.deps.getPersonality();
+        const previousValue = personality[trait] ?? 0.5;
+        let newValue = previousValue + effectiveDelta;
+        // Clamp to [0, 1] range — may further reduce the effective delta
+        if (newValue < 0) {
+            newValue = 0;
+            effectiveDelta = newValue - previousValue;
+            clamped = true;
+        }
+        else if (newValue > 1) {
+            newValue = 1;
+            effectiveDelta = newValue - previousValue;
+            clamped = true;
+        }
+        this.deps.setPersonality(trait, newValue);
+        // Update session tracking
+        const newSessionTotal = currentSessionTotal + Math.abs(effectiveDelta);
+        this.sessionDeltas.set(trait, newSessionTotal);
+        // 6. Record in mutation store
+        this.deps.mutationStore.record({
+            trait,
+            previousValue,
+            newValue,
+            delta: effectiveDelta,
+            reasoning,
+            timestamp: new Date().toISOString(),
+        });
+        // 7. Return result
+        const output = {
+            trait,
+            previousValue,
+            newValue,
+            delta: effectiveDelta,
+            clamped,
+            sessionTotal: newSessionTotal,
+            remainingBudget: maxDeltaPerSession - newSessionTotal,
+        };
+        return { success: true, output };
+    }
+}
+//# sourceMappingURL=AdaptPersonalityTool.js.map

package/dist/emergent/AdaptPersonalityTool.js.map

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

package/dist/emergent/CreateWorkflowTool.d.ts

@@ -0,0 +1,181 @@
+/**
+ * @fileoverview CreateWorkflowTool — ITool implementation that enables agents
+ * to compose multi-step tool workflows at runtime and execute them as a unit.
+ *
+ * @module @framers/agentos/emergent/CreateWorkflowTool
+ *
+ * Agents call `create_workflow` to define, run, and list workflows. A workflow
+ * is a named sequence of tool invocations with reference resolution:
+ * - `$input`     — the workflow's input argument
+ * - `$prev`      — the output of the immediately preceding step
+ * - `$steps[N]`  — the output of the Nth step (zero-indexed)
+ *
+ * Constraints:
+ * - Maximum step count is enforced via `config.maxSteps`.
+ * - Only tools from `config.allowedTools` may be used in steps.
+ * - Recursive workflow creation is blocked (`create_workflow` cannot appear in steps).
+ * - Each step execution has a 30-second timeout enforced via `Promise.race`.
+ */
+import type { ITool, ToolExecutionResult, ToolExecutionContext, JSONSchemaObject } from '../core/tools/ITool.js';
+/**
+ * A single step in a workflow definition.
+ */
+export interface WorkflowStep {
+    /** The tool name to invoke for this step. */
+    tool: string;
+    /** Arguments to pass to the tool (may contain $input, $prev, $steps[N] references). */
+    args: Record<string, unknown>;
+}
+/**
+ * A stored workflow definition with execution metadata.
+ */
+export interface Workflow {
+    /** Unique workflow ID. */
+    id: string;
+    /** Human-readable workflow name. */
+    name: string;
+    /** Natural language description. */
+    description: string;
+    /** Ordered list of steps to execute. */
+    steps: WorkflowStep[];
+    /** ISO-8601 timestamp of creation. */
+    createdAt: string;
+    /** Number of times this workflow has been run. */
+    runCount: number;
+}
+/**
+ * Input arguments accepted by the `create_workflow` tool.
+ * Discriminated on the `action` field.
+ */
+export interface CreateWorkflowInput extends Record<string, any> {
+    /** The action to perform: create, run, or list. */
+    action: 'create' | 'run' | 'list';
+    /** Workflow name (required for create). */
+    name?: string;
+    /** Workflow description (required for create). */
+    description?: string;
+    /** Workflow steps (required for create). */
+    steps?: WorkflowStep[];
+    /** Workflow ID (required for run). */
+    workflowId?: string;
+    /** Input data passed into the workflow when running. */
+    input?: unknown;
+}
+/**
+ * Dependencies injected into the {@link CreateWorkflowTool} constructor.
+ */
+export interface CreateWorkflowDeps {
+    /** Configuration controlling step limits and tool allowlists. */
+    config: {
+        /** Maximum number of steps allowed in a single workflow. */
+        maxSteps: number;
+        /** List of tool names that are permitted in workflow steps. */
+        allowedTools: string[];
+    };
+    /** Execute a tool by name with the given arguments. */
+    executeTool: (name: string, args: unknown) => Promise<unknown>;
+    /** Return the list of all currently available tool names. */
+    listTools: () => string[];
+}
+/**
+ * ITool implementation enabling agents to compose, execute, and list
+ * multi-step tool workflows at runtime.
+ *
+ * @example
+ * ```ts
+ * const tool = new CreateWorkflowTool({
+ *   config: { maxSteps: 10, allowedTools: ['web_search', 'summarize'] },
+ *   executeTool: (name, args) => orchestrator.execute(name, args),
+ *   listTools: () => orchestrator.listToolNames(),
+ * });
+ *
+ * // Create a workflow
+ * const createResult = await tool.execute({
+ *   action: 'create',
+ *   name: 'search-and-summarize',
+ *   description: 'Search the web and summarize results.',
+ *   steps: [
+ *     { tool: 'web_search', args: { query: '$input' } },
+ *     { tool: 'summarize', args: { text: '$prev' } },
+ *   ],
+ * }, context);
+ * ```
+ */
+export declare class CreateWorkflowTool implements ITool<CreateWorkflowInput> {
+    /** @inheritdoc */
+    readonly id = "com.framers.emergent.create-workflow";
+    /** @inheritdoc */
+    readonly name = "create_workflow";
+    /** @inheritdoc */
+    readonly displayName = "Create Workflow";
+    /** @inheritdoc */
+    readonly description: string;
+    /** @inheritdoc */
+    readonly category = "emergent";
+    /** @inheritdoc */
+    readonly hasSideEffects = true;
+    /** @inheritdoc */
+    readonly inputSchema: JSONSchemaObject;
+    /** Session-scoped workflow storage. */
+    private readonly workflows;
+    /** Monotonic counter for generating workflow IDs. */
+    private nextId;
+    /** Injected dependencies. */
+    private readonly deps;
+    /**
+     * Create a new CreateWorkflowTool.
+     *
+     * @param deps - Injected dependencies including config, tool executor,
+     *   and tool lister.
+     */
+    constructor(deps: CreateWorkflowDeps);
+    /**
+     * Execute the requested workflow action.
+     *
+     * @param args - Action type and associated parameters.
+     * @param _context - Tool execution context (unused but required by ITool).
+     * @returns A {@link ToolExecutionResult} wrapping the action outcome.
+     */
+    execute(args: CreateWorkflowInput, _context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    /**
+     * Create and store a new workflow definition.
+     *
+     * Validates:
+     * - Required fields (name, description, steps) are present
+     * - Step count does not exceed maxSteps
+     * - No step references `create_workflow` (prevent recursion)
+     * - All step tools exist in the available tool list
+     */
+    private handleCreate;
+    /**
+     * Run a stored workflow, executing steps sequentially with reference resolution.
+     *
+     * Reference resolution:
+     * - `$input`    — the workflow's input argument
+     * - `$prev`     — the output of the immediately preceding step
+     * - `$steps[N]` — the output of the Nth step (zero-indexed)
+     *
+     * Each step has a 30-second timeout enforced via Promise.race.
+     */
+    private handleRun;
+    /**
+     * List all stored workflows.
+     */
+    private handleList;
+    /**
+     * Resolve `$input`, `$prev`, and `$steps[N]` references in step arguments.
+     *
+     * Uses JSON.stringify → string replacement → JSON.parse cycle for simple
+     * reference resolution. References appearing as standalone string values
+     * are replaced with the actual object; references embedded in larger strings
+     * are serialized inline.
+     *
+     * @param args - The step arguments potentially containing references.
+     * @param input - The workflow input value.
+     * @param prev - The output of the previous step.
+     * @param stepResults - Array of all completed step outputs.
+     * @returns Resolved arguments with references replaced by actual values.
+     */
+    private resolveReferences;
+}
+//# sourceMappingURL=CreateWorkflowTool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CreateWorkflowTool.d.ts","sourceRoot":"","sources":["../../src/emergent/CreateWorkflowTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACV,KAAK,EACL,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAMhC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC9D,mDAAmD;IACnD,MAAM,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAClC,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAMD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,MAAM,EAAE;QACN,4DAA4D;QAC5D,QAAQ,EAAE,MAAM,CAAC;QACjB,+DAA+D;QAC/D,YAAY,EAAE,MAAM,EAAE,CAAC;KACxB,CAAC;IACF,uDAAuD;IACvD,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,6DAA6D;IAC7D,SAAS,EAAE,MAAM,MAAM,EAAE,CAAC;CAC3B;AASD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,kBAAmB,YAAW,KAAK,CAAC,mBAAmB,CAAC;IACnE,kBAAkB;IAClB,QAAQ,CAAC,EAAE,0CAA0C;IAErD,kBAAkB;IAClB,QAAQ,CAAC,IAAI,qBAAqB;IAElC,kBAAkB;IAClB,QAAQ,CAAC,WAAW,qBAAqB;IAEzC,kBAAkB;IAClB,QAAQ,CAAC,WAAW,SAEsC;IAE1D,kBAAkB;IAClB,QAAQ,CAAC,QAAQ,cAAc;IAE/B,kBAAkB;IAClB,QAAQ,CAAC,cAAc,QAAQ;IAE/B,kBAAkB;IAClB,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAqCpC;IAEF,uCAAuC;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoC;IAE9D,qDAAqD;IACrD,OAAO,CAAC,MAAM,CAAK;IAEnB,6BAA6B;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAE1C;;;;;OAKG;gBACS,IAAI,EAAE,kBAAkB;IAQpC;;;;;;OAMG;IACG,OAAO,CACX,IAAI,EAAE,mBAAmB,EACzB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAoB/B;;;;;;;;OAQG;YACW,YAAY;IA4D1B;;;;;;;;;OASG;YACW,SAAS;IAsDvB;;OAEG;YACW,UAAU;IAiBxB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,iBAAiB;CA2B1B"}