@iflow-mcp/jkheadley-instar 0.26.2

package/dist/core/ContextHierarchy.js

@@ -0,0 +1,594 @@
+/**
+ * Context Hierarchy — Tiered context loading for efficient agent awareness.
+ *
+ * Inspired by Dawn's context dispatch system (PROP-088): right context at
+ * the right moment > all context all the time.
+ *
+ * Three tiers:
+ *   Tier 0: Always loaded (identity, project scope, safety rules)
+ *   Tier 1: Session boundaries (continuity, compaction recovery, topic context)
+ *   Tier 2: On-demand (task-specific depth when context matches)
+ *
+ * The hierarchy creates a `.instar/context/` directory with structured
+ * segment files that hooks and sessions can load selectively.
+ *
+ * Born from the Luna incident (2026-02-25): An agent had no systematic
+ * way to load task-relevant context efficiently. Without a hierarchy,
+ * agents either load everything (context bloat) or nothing (incoherence).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** The canonical list of context segments every agent should have. */
+const DEFAULT_SEGMENTS = [
+    {
+        id: 'identity',
+        name: 'Identity & Scope',
+        tier: 0,
+        triggers: ['always'],
+        file: 'identity.md',
+        description: 'Agent name, role, principles, project scope. Always loaded.',
+    },
+    {
+        id: 'safety',
+        name: 'Safety Rules',
+        tier: 0,
+        triggers: ['always'],
+        file: 'safety.md',
+        description: 'Constraints, blocked commands, destructive action rules.',
+    },
+    {
+        id: 'project',
+        name: 'Project Map',
+        tier: 0,
+        triggers: ['always'],
+        file: 'project.md',
+        description: 'Auto-generated project structure, key files, deployment targets.',
+    },
+    {
+        id: 'session',
+        name: 'Session Continuity',
+        tier: 1,
+        triggers: ['session-start', 'compaction', 'resume'],
+        file: 'session.md',
+        description: 'Session lifecycle, ownership, recovery procedures.',
+    },
+    {
+        id: 'relationships',
+        name: 'Relationship Context',
+        tier: 1,
+        triggers: ['session-start', 'messaging'],
+        file: 'relationships.md',
+        description: 'Known people, interaction patterns, relationship maintenance.',
+    },
+    {
+        id: 'development',
+        name: 'Development Patterns',
+        tier: 2,
+        triggers: ['writing-code', 'modifying-files', 'debugging'],
+        file: 'development.md',
+        description: 'Code conventions, testing patterns, architectural decisions for this project.',
+    },
+    {
+        id: 'deployment',
+        name: 'Deployment Guide',
+        tier: 2,
+        triggers: ['deploying', 'building', 'pushing-to-git'],
+        file: 'deployment.md',
+        description: 'Deployment targets, CI/CD setup, environment variables, rollback procedures.',
+    },
+    {
+        id: 'communication',
+        name: 'Communication Patterns',
+        tier: 2,
+        triggers: ['messaging-user', 'sending-email', 'writing-report'],
+        file: 'communication.md',
+        description: 'User preferences, tone guidelines, when to proactively reach out.',
+    },
+    {
+        id: 'architecture',
+        name: 'Architecture & Features',
+        tier: 2,
+        triggers: ['answering-architecture-questions', 'explaining-features', 'multi-user-setup', 'multi-machine-setup'],
+        file: 'architecture.md',
+        description: 'System architecture, feature inventory, multi-user/multi-machine distinctions. ALWAYS consult /capabilities first.',
+    },
+    {
+        id: 'research',
+        name: 'Research Navigation',
+        tier: 2,
+        triggers: ['researching', 'searching-broadly', 'spawning-agents', 'web-fetching', 'checking-state'],
+        file: 'research-navigation.md',
+        description: 'Canonical source hierarchy — check state files BEFORE broad searches. Web fetch optimization via smart-fetch.',
+    },
+];
+export class ContextHierarchy {
+    config;
+    contextDir;
+    constructor(config) {
+        this.config = config;
+        this.contextDir = path.join(config.stateDir, 'context');
+    }
+    /**
+     * Initialize the context directory with default segment files.
+     * Only creates files that don't already exist (additive only).
+     */
+    initialize() {
+        fs.mkdirSync(this.contextDir, { recursive: true });
+        const created = [];
+        const skipped = [];
+        for (const segment of DEFAULT_SEGMENTS) {
+            const filePath = path.join(this.contextDir, segment.file);
+            if (fs.existsSync(filePath)) {
+                skipped.push(segment.file);
+                continue;
+            }
+            const content = this.generateSegmentTemplate(segment);
+            fs.writeFileSync(filePath, content);
+            created.push(segment.file);
+        }
+        // Write the dispatch table
+        this.writeDispatchTable();
+        return { created, skipped };
+    }
+    /**
+     * Get the dispatch table — a mapping of triggers to context files.
+     * This is what agents read to know "when X happens, load Y."
+     */
+    getDispatchTable() {
+        return DEFAULT_SEGMENTS
+            .filter(s => s.tier === 2)
+            .flatMap(s => s.triggers.map(trigger => ({
+            trigger,
+            file: `.instar/context/${s.file}`,
+            reason: s.description,
+        })));
+    }
+    /**
+     * Write the dispatch table to a human-readable file.
+     */
+    writeDispatchTable() {
+        const table = this.getDispatchTable();
+        const lines = [
+            '# Context Dispatch Table',
+            '',
+            '> When certain work arises, deeper context helps you be fully present.',
+            '> This table guides which context to surface.',
+            '',
+            '| When you\'re about to... | Read this context | Why |',
+            '|------------------------|-------------------|-----|',
+        ];
+        for (const entry of table) {
+            lines.push(`| ${entry.trigger} | \`${entry.file}\` | ${entry.reason} |`);
+        }
+        // Add tier 0 and 1 explanations
+        lines.push('');
+        lines.push('## Always-Loaded Context (Tier 0)');
+        lines.push('');
+        lines.push('These are injected automatically at every session start:');
+        for (const s of DEFAULT_SEGMENTS.filter(s => s.tier === 0)) {
+            lines.push(`- \`.instar/context/${s.file}\` — ${s.description}`);
+        }
+        lines.push('');
+        lines.push('## Session-Boundary Context (Tier 1)');
+        lines.push('');
+        lines.push('These are loaded at session start, compaction, and resume:');
+        for (const s of DEFAULT_SEGMENTS.filter(s => s.tier === 1)) {
+            lines.push(`- \`.instar/context/${s.file}\` — ${s.description}`);
+        }
+        lines.push('');
+        lines.push('*Auto-generated by Instar Context Hierarchy.*');
+        fs.writeFileSync(path.join(this.contextDir, 'DISPATCH.md'), lines.join('\n'));
+    }
+    /**
+     * Load all segments for a given tier.
+     * Returns concatenated content suitable for hook injection.
+     */
+    loadTier(tier) {
+        const segments = DEFAULT_SEGMENTS.filter(s => s.tier <= tier);
+        const parts = [];
+        for (const segment of segments) {
+            const filePath = path.join(this.contextDir, segment.file);
+            if (fs.existsSync(filePath)) {
+                try {
+                    const content = fs.readFileSync(filePath, 'utf-8').trim();
+                    if (content && !content.startsWith('<!--') || content.includes('\n\n')) {
+                        parts.push(content);
+                    }
+                }
+                catch {
+                    // @silent-fallback-ok — segment load, empty string
+                }
+            }
+        }
+        return parts.join('\n\n');
+    }
+    /**
+     * Load a specific context segment by ID.
+     */
+    loadSegment(segmentId) {
+        const segment = DEFAULT_SEGMENTS.find(s => s.id === segmentId);
+        if (!segment)
+            return null;
+        const filePath = path.join(this.contextDir, segment.file);
+        try {
+            if (fs.existsSync(filePath)) {
+                return fs.readFileSync(filePath, 'utf-8');
+            }
+        }
+        catch {
+            // @silent-fallback-ok — segment load returns null
+        }
+        return null;
+    }
+    /**
+     * List all context segments with their status.
+     */
+    listSegments() {
+        return DEFAULT_SEGMENTS.map(s => {
+            const filePath = path.join(this.contextDir, s.file);
+            let exists = false;
+            let sizeBytes = 0;
+            try {
+                if (fs.existsSync(filePath)) {
+                    exists = true;
+                    sizeBytes = fs.statSync(filePath).size;
+                }
+            }
+            catch { /* ignore */ }
+            return { ...s, exists, sizeBytes };
+        });
+    }
+    /**
+     * Get the context directory path.
+     */
+    getContextDir() {
+        return this.contextDir;
+    }
+    // ── Template Generation ─────────────────────────────────────────
+    generateSegmentTemplate(segment) {
+        switch (segment.id) {
+            case 'identity':
+                return this.identityTemplate();
+            case 'safety':
+                return this.safetyTemplate();
+            case 'project':
+                return this.projectTemplate();
+            case 'session':
+                return this.sessionTemplate();
+            case 'relationships':
+                return this.relationshipsTemplate();
+            case 'development':
+                return this.developmentTemplate();
+            case 'deployment':
+                return this.deploymentTemplate();
+            case 'communication':
+                return this.communicationTemplate();
+            case 'architecture':
+                return this.architectureTemplate();
+            case 'research':
+                return `# Research & Navigation\n\n<!-- Add research navigation context here -->\n`;
+            default:
+                return `# ${segment.name}\n\n<!-- Add context for: ${segment.description} -->\n`;
+        }
+    }
+    identityTemplate() {
+        return `# Identity & Scope
+
+<!-- This file is auto-generated by Instar. Customize it for your agent. -->
+
+## Who I Am
+
+Read .instar/AGENT.md for full identity. This is a quick-reference summary.
+
+## Project Scope
+
+- **Project**: ${this.config.projectName}
+- **Directory**: ${this.config.projectDir}
+- Read .instar/project-map.md for full project structure.
+
+## Core Truths
+
+1. I am a builder. When I see work, I do it.
+2. I know my tools. I check /capabilities before saying "I can't."
+3. I verify before claiming. "Did I actually check this, or am I assuming?"
+`;
+    }
+    safetyTemplate() {
+        return `# Safety Rules
+
+## Hard Blocks
+
+These commands are ALWAYS blocked regardless of context:
+- \`rm -rf /\` or \`rm -rf ~\` — catastrophic filesystem destruction
+- \`> /dev/sda\` — disk overwrite
+- Fork bombs, disk formatting commands
+
+## Soft Blocks (Safety Level Dependent)
+
+At Safety Level 1 (default): ask user before running.
+At Safety Level 2 (autonomous): self-verify before running.
+
+- \`git push --force\` — overwrites remote history
+- \`git reset --hard\` — discards uncommitted work
+- \`DROP TABLE/DATABASE\` — irreversible data loss
+- \`rm -rf .\` — project directory destruction
+
+## Coherence Gate
+
+Before deploying, pushing, or modifying files outside this project:
+1. Check coherence: POST /coherence/check
+2. If BLOCK — stop. You're likely in the wrong project.
+3. If WARN — pause and verify.
+
+## Topic-Project Bindings
+
+Each Telegram topic may be bound to a specific project. Verify before acting.
+`;
+    }
+    projectTemplate() {
+        return `# Project Context
+
+<!-- Auto-populated from project-map.json. Refresh: POST /project-map/refresh -->
+
+Read .instar/project-map.md for the full project structure map.
+Read .instar/project-map.json for programmatic access.
+
+Quick reference: GET /project-map?format=compact
+`;
+    }
+    sessionTemplate() {
+        return `# Session Continuity
+
+## On Session Start
+
+1. Note the current topic (if Telegram session)
+2. Read thread history for conversational context
+3. Check for pending upgrade guides
+4. Verify identity (AGENT.md exists and is readable)
+
+## On Compaction
+
+Context was compressed. Recovery priority:
+1. Topic context (what am I working on?)
+2. Identity (who am I?)
+3. Memory (what have I learned?)
+4. Project context (where am I?)
+5. Capabilities (what can I do?)
+
+## On Resume
+
+Re-read recent activity. Check if anything changed while you were paused.
+
+## Session Handoff
+
+When ending a session that another might continue:
+- Update MEMORY.md with anything learned
+- Note any incomplete work
+- Save conversation context via topic memory
+`;
+    }
+    relationshipsTemplate() {
+        return `# Relationship Context
+
+## Before Interacting with Anyone
+
+1. Check if they're tracked: GET /relationships
+2. If tracked, read their file for context before responding
+3. Note the interaction type and update the relationship record after
+
+## Key Patterns
+
+- **First contact**: Be welcoming but verify identity
+- **Returning user**: Reference shared history naturally
+- **Stale contact**: Consider reaching out if significance >= 3
+
+## Relationship Files
+
+All relationship records are in .instar/relationships/*.json
+Each contains: name, interactions, significance, themes, notes
+`;
+    }
+    developmentTemplate() {
+        return `# Development Patterns
+
+<!-- Customize this for your project's specific conventions. -->
+
+## Before Writing Code
+
+1. Read existing code before modifying it
+2. Check the project map for file locations
+3. Follow existing patterns in the codebase
+
+## Testing
+
+- Run tests before committing
+- Match the project's existing test patterns
+- Write tests for new features
+
+## Git Workflow
+
+- Commit with clear messages
+- Check coherence gate before pushing
+- Verify CI passes after push
+
+## Project-Specific Conventions
+
+<!-- Add your project's coding standards, linting rules,
+     naming conventions, architecture patterns, etc. -->
+`;
+    }
+    deploymentTemplate() {
+        return `# Deployment Guide
+
+<!-- Customize this for your project's deployment setup. -->
+
+## Pre-Deployment Checklist
+
+1. Run coherence check: POST /coherence/check with action "deploy"
+2. Verify you're in the correct project directory
+3. Verify the deployment target matches the current topic/project
+4. Run tests
+5. Check CI status: GET /ci
+
+## Deployment Targets
+
+<!-- List your deployment targets here, e.g.:
+- Production: https://myapp.vercel.app (Vercel)
+- Staging: https://staging.myapp.com
+-->
+
+Check project map for auto-detected targets: GET /project-map
+
+## Rollback Procedure
+
+<!-- Document how to rollback if a deployment goes wrong -->
+
+## Environment Variables
+
+<!-- List required environment variables and where they're configured -->
+`;
+    }
+    communicationTemplate() {
+        return `# Communication Patterns
+
+## Telegram
+
+- Always acknowledge messages immediately
+- Relay responses via telegram-reply script
+- Strip [telegram:N] prefix before interpreting
+- Read thread history for context on new sessions
+
+## Reporting
+
+- Use Private Viewer for sensitive content (POST /view)
+- Use Telegraph for public content (POST /publish)
+- Always include artifact links, not just summaries
+
+## User Preferences
+
+<!-- Document your user's communication preferences:
+- Preferred response length
+- When to proactively reach out
+- When to stay silent
+- Topics they care about vs. internal details
+-->
+`;
+    }
+    architectureTemplate() {
+        return `# Architecture & Features
+
+## MANDATORY: Look Up Before Answering
+
+When anyone asks about Instar features, architecture, or how things work:
+1. Run \`curl -s -H "Authorization: Bearer $AUTH" http://localhost:PORT/capabilities\`
+2. Read the relevant section of the response
+3. THEN answer based on what you found
+
+Never answer architecture questions from memory. The system describes itself.
+
+## Key Architectural Distinctions
+
+### Multi-Machine vs Multi-User
+- **Multi-machine** (\`instar pair\` / \`instar join\`): One agent across YOUR multiple devices
+- **Multi-user**: Different people interacting with this agent via Telegram or API
+- **Different agents**: Separate Instar instances, separate identities
+
+### User Registration
+Check \`/capabilities\` for the \`users\` section. Registration policies:
+- \`open\` — anyone can register
+- \`invite-only\` — requires invite code
+- \`admin-only\` — only the admin can add users (default)
+
+### Telegram Architecture
+- One bot token per agent instance (polling conflict if shared)
+- Users join the agent's Telegram group to interact
+- Each topic can be bound to a project (coherence scoping)
+
+## Self-Describing Endpoints
+
+| What | Endpoint |
+|------|----------|
+| Full capability matrix | GET /capabilities |
+| Context dispatch table | GET /context/dispatch |
+| All context segments | GET /context |
+| Project structure | GET /project-map |
+| Quick facts | GET /state/quick-facts |
+| CLI commands | \`instar --help\` |
+`;
+    }
+    researchNavigationTemplate() {
+        return `# Research Navigation
+
+> "Don't drive around looking for the building. Check the address first."
+
+## Canonical Sources — Check BEFORE Broad Searches
+
+For ANY question about current state, check the canonical source FIRST.
+Only explore broadly if the canonical source doesn't answer the question.
+
+| Question Category | Check First | Path / Command |
+|---|---|---|
+| What state is [X] in? | Quick Facts | \`GET /state/quick-facts\` or \`.instar/state/quick-facts.json\` |
+| What NOT to do? | Anti-Patterns | \`GET /state/anti-patterns\` or \`.instar/state/anti-patterns.json\` |
+| What projects exist? | Project Registry | \`GET /state/project-registry\` or \`.instar/state/project-registry.json\` |
+| What features are available? | Capabilities | \`GET /capabilities\` |
+| What jobs are scheduled? | Job State | \`GET /jobs\` or \`.instar/state/job-state.json\` |
+| Who is [person]? | Relationships | \`.instar/relationships/\` directory |
+| What happened in session X? | Session Reports | \`.instar/sessions/[ID]/report.md\` |
+| What proposals are pending? | Evolution Queue | \`GET /evolution/proposals\` |
+| What gaps exist? | Capability Gaps | \`GET /evolution/gaps\` |
+| What learnings do I have? | Learning Registry | \`GET /evolution/learnings\` |
+
+## The Hierarchy (When Sources Conflict)
+
+\`\`\`
+1. Server API responses (GET /state/*, /capabilities)
+   → Live, computed from current state
+
+2. JSON state files (.instar/state/*.json)
+   → Canonical on-disk state, designed to be current
+
+3. Agent identity files (AGENT.md, soul.md)
+   → Stable identity, rarely stale
+
+4. Session reports (.instar/sessions/*/report.md)
+   → Historical narrative — may describe PAST state
+
+5. Broad search results (grep/explore)
+   → Useful for discovery, unreliable for current state
+\`\`\`
+
+When a state file says X and a session report says not-X: the state file wins.
+
+## Web Content Fetching
+
+When fetching content from ANY URL, use the efficient method first:
+
+\`\`\`
+1. python3 .instar/scripts/smart-fetch.py URL --auto
+   → Checks llms.txt (machine-readable site map)
+   → Tries Accept: text/markdown (Cloudflare, ~80% token savings)
+   → Falls back to HTML text extraction
+
+2. WebFetch (built-in Claude Code tool)
+   → For URLs where smart-fetch isn't practical
+
+3. WebSearch / Exa MCP
+   → For discovery when you don't have a URL
+
+4. Playwright/Chrome MCP
+   → ONLY for pages requiring JS rendering or interaction
+\`\`\`
+
+## For Spawned Agents
+
+When spawning research agents, include canonical sources in the prompt:
+
+**Instead of**: "Search for deployment config across the codebase"
+**Use**: "First check \`.instar/state/quick-facts.json\` for deployment entries. If that doesn't answer it, search broadly."
+
+The agent prompt IS the seed. If the seed doesn't include the map, the agent searches blind.
+`;
+    }
+}
+//# sourceMappingURL=ContextHierarchy.js.map

package/dist/core/ContextHierarchy.js.map

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

package/dist/core/ContextSnapshotBuilder.d.ts

@@ -0,0 +1,80 @@
+/**
+ * ContextSnapshotBuilder — Builds structured agent context snapshots.
+ *
+ * Produces an AgentContextSnapshot by reading config, AGENT.md, jobs,
+ * decisions, autonomy profile, and applied dispatches. Designed for:
+ *
+ * 1. Dispatch evaluation (Discernment Layer) — LLM needs agent context
+ * 2. General agent self-awareness — any system that needs "who am I?"
+ *
+ * Data minimization: only structural metadata, no sensitive operational
+ * details (relationship data, specific decision content).
+ *
+ * Token budget: ~300 tokens (concise) to ~800 tokens (detailed).
+ * Hard truncation enforced before returning.
+ *
+ * Caching: snapshots cached with configurable TTL (default: 10 minutes).
+ */
+import type { AgentContextSnapshot } from './types.js';
+export interface ContextSnapshotConfig {
+    /** Max chars for identity.intent field (default: 800 ≈ 200 tokens) */
+    maxIntentChars?: number;
+    /** Max recent decisions to include (default: 20) */
+    maxRecentDecisions?: number;
+    /** Max chars per decision string (default: 100) */
+    maxDecisionChars?: number;
+    /** Max active jobs to include (default: 20) */
+    maxActiveJobs?: number;
+    /** Cache TTL in milliseconds (default: 600000 = 10 minutes) */
+    cacheTtlMs?: number;
+    /** Detail level: 'concise' (~300 tokens) or 'detailed' (~800 tokens) */
+    detailLevel?: 'concise' | 'detailed';
+}
+interface SnapshotSources {
+    /** Agent project name */
+    projectName: string;
+    /** Path to the project root (for AGENT.md) */
+    projectDir: string;
+    /** Path to .instar state directory */
+    stateDir: string;
+    /** Jobs file path (for active jobs) */
+    jobsFile?: string;
+}
+export declare class ContextSnapshotBuilder {
+    private sources;
+    private config;
+    private cachedSnapshot;
+    private cacheTimestamp;
+    constructor(sources: SnapshotSources, config?: ContextSnapshotConfig);
+    /**
+     * Build a context snapshot. Returns cached version if within TTL.
+     */
+    build(): AgentContextSnapshot;
+    /**
+     * Force-invalidate the cache. Call when config or jobs change.
+     */
+    invalidateCache(): void;
+    /**
+     * Render the snapshot as a text string for LLM prompts.
+     */
+    renderForPrompt(snapshot?: AgentContextSnapshot): string;
+    /**
+     * Produce an external-shareable snapshot (further minimized).
+     * Strips decision content, job descriptions, intent details.
+     */
+    buildExternalSnapshot(): Partial<AgentContextSnapshot>;
+    private buildIdentity;
+    private buildCapabilities;
+    private buildActiveJobs;
+    private buildRecentDecisions;
+    private readAutonomyLevel;
+    private buildAppliedDispatchSummary;
+    private extractDescription;
+    private extractIntent;
+    /**
+     * Read self-knowledge tree metadata if available.
+     */
+    private readSelfKnowledgeMetadata;
+}
+export {};
+//# sourceMappingURL=ContextSnapshotBuilder.d.ts.map

package/dist/core/ContextSnapshotBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextSnapshotBuilder.d.ts","sourceRoot":"","sources":["../../src/core/ContextSnapshotBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EACV,oBAAoB,EAIrB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,WAAW,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;CACtC;AAED,UAAU,eAAe;IACvB,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAWD,qBAAa,sBAAsB;IACjC,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,cAAc,CAAqC;IAC3D,OAAO,CAAC,cAAc,CAAa;gBAEvB,OAAO,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,qBAAqB;IAKpE;;OAEG;IACH,KAAK,IAAI,oBAAoB;IAsB7B;;OAEG;IACH,eAAe,IAAI,IAAI;IAKvB;;OAEG;IACH,eAAe,CAAC,QAAQ,CAAC,EAAE,oBAAoB,GAAG,MAAM;IAiDxD;;;OAGG;IACH,qBAAqB,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAiBtD,OAAO,CAAC,aAAa;IAyBrB,OAAO,CAAC,iBAAiB;IAgDzB,OAAO,CAAC,eAAe;IAuBvB,OAAO,CAAC,oBAAoB;IA6B5B,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,2BAA2B;IAuBnC,OAAO,CAAC,kBAAkB;IAa1B,OAAO,CAAC,aAAa;IASrB;;OAEG;IACH,OAAO,CAAC,yBAAyB;CAqClC"}