@nac3/forge-cli 0.2.0-alpha.9 → 1.0.0

package/dist/core/turn_classifier.js

@@ -0,0 +1,324 @@
+/**
+ * turn_classifier.ts -- Gemini mini-prompt that decides tier for
+ * a turn the reasoning_gate flagged as ambiguous (alpha.55).
+ *
+ * Why eco-model for the classifier itself: the question
+ * "simple verb invocation or complex reasoning?" is a routing
+ * decision, not a content decision. Gemini Flash Lite handles it
+ * in ~400 ms for fractions of a cent. The verdict gates whether
+ * the EXPENSIVE turn (full LLM call) goes to eco or frontier.
+ *
+ * Fallback path when Gemini is not reachable or the key is
+ * missing: the gate's own (low-confidence) tier suggestion is
+ * returned with a "classifier_unreachable" signal so the cost log
+ * shows what happened. The chat NEVER blocks on classifier
+ * availability.
+ *
+ * Cache: LRU keyed by sha256 of the user text + previous tier.
+ * 50 entries / 5 min TTL. Saves the classifier call on repeated
+ * short prompts ("hola", "ok", "si").
+ *
+ * ASCII-only.
+ */
+import { createHash } from 'node:crypto';
+const SYSTEM_PROMPT = ('You are a routing classifier inside a developer tool. Given a ' +
+    'user message, decide which class it belongs to:\n' +
+    '  - "simple": a short request invoking one tool or asking a ' +
+    'trivial question. Examples: "abrime una tab", "show me the ' +
+    'budget", "list pipelines", "hola", "leeme la tabla", ' +
+    '"que hora es", "cual es el current branch".\n' +
+    '  - "complex": requires reasoning, design, code generation, ' +
+    'a multi-step plan, OR loading / summarising project context ' +
+    '(the graph, the pendings, the wiring, the doctrines). ' +
+    'Examples: "design the architecture for X", "implement a ' +
+    'new feature", "refactor this module", "write a function ' +
+    'that does Y", "estamos parados en el proyecto X, podes ' +
+    'subir todo el know how", "carga el contexto del proyecto", ' +
+    '"que sabes sobre este proyecto", "muestrame el grafo del ' +
+    'proyecto", "lista los pendientes y dame un resumen", ' +
+    '"que doctrinas tenes activas", "explicame el estado del ' +
+    'proyecto", "que tenes guardado sobre yuemail".\n' +
+    '  - "destructive": modifies persistent state (delete files, drop ' +
+    'tables, commit + push, send emails, deploy). Examples: "borra ' +
+    'esos archivos", "git push --force", "send the email now".\n\n' +
+    'Reply with exactly one word: simple, complex, or destructive. ' +
+    'No punctuation, no extra text.');
+const CACHE_MAX = 50;
+const CACHE_TTL_MS = 5 * 60 * 1000;
+const _cache = new Map();
+function cacheKey(text, prev) {
+    const h = createHash('sha256');
+    h.update(prev || '');
+    h.update('|');
+    h.update(text);
+    return h.digest('hex');
+}
+function cacheGet(key) {
+    const e = _cache.get(key);
+    if (!e)
+        return null;
+    if (Date.now() - e.ts > CACHE_TTL_MS) {
+        _cache.delete(key);
+        return null;
+    }
+    /* Move to end -> LRU touch. */
+    _cache.delete(key);
+    _cache.set(key, e);
+    return { ...e.result, cached: true };
+}
+function cacheSet(key, result) {
+    if (_cache.size >= CACHE_MAX) {
+        /* Drop oldest (first inserted) -- Map iteration order is
+         *  insertion order. */
+        const first = _cache.keys().next().value;
+        if (first !== undefined)
+            _cache.delete(first);
+    }
+    _cache.set(key, { ts: Date.now(), result: { ...result, cached: false } });
+}
+/** Test hook -- clear cache between specs. */
+export function _resetClassifierCache() {
+    _cache.clear();
+}
+/* ----- classifier core ------------------------------------- */
+function parseVerdict(text) {
+    const t = (text || '').trim().toLowerCase();
+    /* Gemini sometimes wraps the word in markdown or punctuation. */
+    const stripped = t.replace(/[^a-z]/g, '');
+    if (stripped === 'simple')
+        return 'simple';
+    if (stripped === 'complex')
+        return 'complex';
+    if (stripped === 'destructive')
+        return 'destructive';
+    /* Substring fallback for noisy output. */
+    if (stripped.includes('simple'))
+        return 'simple';
+    if (stripped.includes('complex'))
+        return 'complex';
+    if (stripped.includes('destructive'))
+        return 'destructive';
+    return null;
+}
+function verdictToTier(v, gate_tier) {
+    if (v === 'simple')
+        return 'eco';
+    if (v === 'complex')
+        return 'frontier';
+    /* destructive routes to frontier so the user gets the best
+     *  judgment before persistent changes. */
+    if (v === 'destructive')
+        return 'frontier';
+    /* null -> gate fallback. */
+    return gate_tier;
+}
+async function callGemini(text, apiKey, model, fetchImpl, timeoutMs) {
+    /* PND-051 (parcial) -- key por header, no por query string:
+     * las URLs terminan en logs de proxies/observabilidad. */
+    const url = 'https://generativelanguage.googleapis.com/v1beta/models/' +
+        encodeURIComponent(model) + ':generateContent';
+    const body = {
+        systemInstruction: { parts: [{ text: SYSTEM_PROMPT }] },
+        contents: [{
+                role: 'user',
+                parts: [{ text: text.slice(0, 2000) }],
+            }],
+        generationConfig: {
+            maxOutputTokens: 8,
+            temperature: 0.0,
+        },
+    };
+    /* alpha.59z.188 PND-040 -- one-shot retry on 5xx / network error.
+     * 4xx (400 / 401 / 403) does NOT retry (client-side problem; the
+     * request is broken, the second try is broken too). 429 retries
+     * once after a brief backoff. 5xx retries once with no delay. */
+    async function attempt(retry) {
+        const controller = new AbortController();
+        const t = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const r = await fetchImpl(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'x-goog-api-key': apiKey,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!r.ok) {
+                const status = r.status;
+                if (retry && (status === 429 || status >= 500)) {
+                    if (status === 429) {
+                        /* Pause ~400ms before retrying to let any per-second
+                         *  quota window close. */
+                        await new Promise((res) => setTimeout(res, 400));
+                    }
+                    return await attempt(false);
+                }
+                /* PND-066 -- incluir un snippet del body en el error: un
+                 * "http 400" pelado no diagnostica nada (lo sufrimos en
+                 * la sesion Yuemail 2026-06-10). El body de error de la
+                 * API nunca contiene la key. */
+                let detail = '';
+                try {
+                    detail = (await r.text()).slice(0, 120).replace(/\s+/g, ' ');
+                }
+                catch { /* ignore */ }
+                throw new Error('gemini http ' + status + (detail ? ' ' + detail : ''));
+            }
+            const j = await r.json();
+            const candidate = j.candidates && j.candidates[0];
+            const part = candidate?.content?.parts && candidate.content.parts[0];
+            return (part && typeof part.text === 'string') ? part.text : '';
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            const isNetwork = /ENOTFOUND|ECONNRESET|ETIMEDOUT|aborted|fetch failed|getaddrinfo/i.test(msg);
+            if (retry && isNetwork) {
+                return await attempt(false);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+    return attempt(true);
+}
+/** PND-066 -- Anthropic path: Haiku tambien resuelve la
+ *  clasificacion de una palabra por fracciones de centavo. Misma
+ *  semantica de retry que callGemini: 5xx/red reintenta una vez,
+ *  4xx no (request roto), 429 reintenta tras una pausa breve. */
+async function callAnthropic(text, apiKey, model, fetchImpl, timeoutMs) {
+    const url = 'https://api.anthropic.com/v1/messages';
+    const body = {
+        model,
+        max_tokens: 8,
+        temperature: 0.0,
+        system: SYSTEM_PROMPT,
+        messages: [{ role: 'user', content: text.slice(0, 2000) }],
+    };
+    async function attempt(retry) {
+        const controller = new AbortController();
+        const t = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const r = await fetchImpl(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'x-api-key': apiKey,
+                    'anthropic-version': '2023-06-01',
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!r.ok) {
+                const status = r.status;
+                if (retry && (status === 429 || status >= 500)) {
+                    if (status === 429) {
+                        await new Promise((res) => setTimeout(res, 400));
+                    }
+                    return await attempt(false);
+                }
+                let detail = '';
+                try {
+                    detail = (await r.text()).slice(0, 120).replace(/\s+/g, ' ');
+                }
+                catch { /* ignore */ }
+                throw new Error('anthropic http ' + status + (detail ? ' ' + detail : ''));
+            }
+            const j = await r.json();
+            const block = Array.isArray(j.content)
+                ? j.content.find((b) => typeof b?.text === 'string')
+                : undefined;
+            return block && typeof block.text === 'string' ? block.text : '';
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            const isNetwork = /ENOTFOUND|ECONNRESET|ETIMEDOUT|aborted|fetch failed|getaddrinfo/i.test(msg);
+            if (retry && isNetwork) {
+                return await attempt(false);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+    return attempt(true);
+}
+/**
+ * Run the classifier. Never throws -- on any failure, returns
+ * the gate's fallback tier with a "classifier_unreachable"
+ * signal and confidence 0.50.
+ */
+export async function classifyTurn(input) {
+    const text = typeof input.text === 'string' ? input.text : '';
+    const key = cacheKey(text, input.previous_tier);
+    const cached = cacheGet(key);
+    if (cached)
+        return cached;
+    const signals = [];
+    const apiKey = input.api_key ?? null;
+    if (!apiKey) {
+        signals.push('classifier_no_api_key');
+        const r = {
+            tier: input.gate_tier,
+            confidence: 0.50,
+            verdict: null,
+            signals,
+            cached: false,
+        };
+        cacheSet(key, r);
+        return r;
+    }
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const provider = input.provider ?? 'google_ai';
+    const model = input.model
+        ?? (provider === 'anthropic' ? 'claude-haiku-4-5-20251001' : 'gemini-2.5-flash-lite');
+    const timeoutMs = input.timeoutMs ?? 2500;
+    let raw = '';
+    try {
+        raw = provider === 'anthropic'
+            ? await callAnthropic(text, apiKey, model, fetchImpl, timeoutMs)
+            : await callGemini(text, apiKey, model, fetchImpl, timeoutMs);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        signals.push('classifier_unreachable[' + msg.slice(0, 60) + ']');
+        const r = {
+            tier: input.gate_tier,
+            confidence: 0.50,
+            verdict: null,
+            signals,
+            cached: false,
+        };
+        cacheSet(key, r);
+        return r;
+    }
+    const verdict = parseVerdict(raw);
+    if (!verdict) {
+        signals.push('classifier_unparseable[' + raw.slice(0, 30) + ']');
+        const r = {
+            tier: input.gate_tier,
+            confidence: 0.50,
+            verdict: null,
+            signals,
+            cached: false,
+        };
+        cacheSet(key, r);
+        return r;
+    }
+    signals.push('classifier_verdict[' + verdict + ']');
+    const tier = verdictToTier(verdict, input.gate_tier);
+    const r = {
+        tier,
+        confidence: verdict === 'destructive' ? 0.95 : 0.88,
+        verdict,
+        signals,
+        cached: false,
+    };
+    cacheSet(key, r);
+    return r;
+}
+//# sourceMappingURL=turn_classifier.js.map

package/dist/core/turn_classifier.js.map

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

package/dist/core/vad_config.d.ts

@@ -0,0 +1,34 @@
+export type VadEngine = 'amplitude' | 'freq-band';
+export interface VadConfig {
+    engine: VadEngine;
+    /** Ambient sampling window before classifying a tick as speech. */
+    baseline_ms: number;
+    /** Speech detection threshold = baseline * mult, clamped by min/max. */
+    threshold_mult: number;
+    /** Floor for the dynamic threshold (very quiet rooms). */
+    min_threshold: number;
+    /** Ceiling for the dynamic threshold (very loud rooms). */
+    max_threshold: number;
+    /** Sustained silence after a voiced segment to close the capture. */
+    silence_ms: number;
+    /** Minimum voiced duration to confirm "speech started" (anti-blip). */
+    min_voiced_ms: number;
+    /** Tick interval for the VAD loop. */
+    tick_ms: number;
+    /** Show a live debug overlay (top-right corner of the panel). */
+    debug_overlay: boolean;
+    /** Emit a JSONL session-stats row at end of each capture. */
+    session_stats: boolean;
+    /** freq-band specific: low end of the voice band in Hz. */
+    freq_low_hz: number;
+    /** freq-band specific: high end of the voice band in Hz. */
+    freq_high_hz: number;
+}
+export declare const DEFAULT_VAD_CONFIG: VadConfig;
+/** Validate + sanitize a config payload coming from disk or panel. */
+export declare function sanitiseVadConfig(input: unknown): VadConfig;
+export declare function readVadConfig(): Promise<VadConfig>;
+export declare function writeVadConfig(cfg: VadConfig): Promise<void>;
+/** Append a VAD session-stats row to ~/.yujin-forge/vad_sessions.jsonl. */
+export declare function appendVadSessionStats(row: Record<string, unknown>): Promise<void>;
+//# sourceMappingURL=vad_config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vad_config.d.ts","sourceRoot":"","sources":["../../src/core/vad_config.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC;AAElD,MAAM,WAAW,SAAS;IACxB,MAAM,EAAU,SAAS,CAAC;IAC1B,mEAAmE;IACnE,WAAW,EAAK,MAAM,CAAC;IACvB,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,aAAa,EAAG,MAAM,CAAC;IACvB,2DAA2D;IAC3D,aAAa,EAAG,MAAM,CAAC;IACvB,qEAAqE;IACrE,UAAU,EAAM,MAAM,CAAC;IACvB,uEAAuE;IACvE,aAAa,EAAG,MAAM,CAAC;IACvB,sCAAsC;IACtC,OAAO,EAAS,MAAM,CAAC;IACvB,iEAAiE;IACjE,aAAa,EAAG,OAAO,CAAC;IACxB,6DAA6D;IAC7D,aAAa,EAAG,OAAO,CAAC;IACxB,2DAA2D;IAC3D,WAAW,EAAK,MAAM,CAAC;IACvB,4DAA4D;IAC5D,YAAY,EAAI,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,kBAAkB,EAAE,SAahC,CAAC;AAkBF,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAiB3D;AAED,wBAAsB,aAAa,IAAI,OAAO,CAAC,SAAS,CAAC,CASxD;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAOlE;AAED,2EAA2E;AAC3E,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvF"}

package/dist/core/vad_config.js

@@ -0,0 +1,95 @@
+/**
+ * VAD (Voice Activity Detection) tuning config.
+ *
+ * Persisted at `~/.yujin-forge/vad_config.json`. Read by the chat
+ * server at boot + on every change, broadcast to the panel so the
+ * VAD loop can hot-apply without a reload. PND-003.
+ *
+ * Two detection engines:
+ *  - `amplitude` (default, alpha.45 shape) -- RMS over the time
+ *    domain, baseline*mult adaptive threshold.
+ *  - `freq-band`  -- band-pass energy on 80-400Hz (human voice
+ *    fundamentals) over the frequency domain, baseline*mult against
+ *    only that band. Better at rejecting fan / AC / music hum that
+ *    has energy outside the voice band.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { renameWithRetry } from './atomic_write.js';
+export const DEFAULT_VAD_CONFIG = {
+    engine: 'amplitude',
+    baseline_ms: 600,
+    threshold_mult: 3.0,
+    min_threshold: 0.012,
+    max_threshold: 0.06,
+    silence_ms: 1000,
+    min_voiced_ms: 200,
+    tick_ms: 50,
+    debug_overlay: false,
+    session_stats: false,
+    freq_low_hz: 80,
+    freq_high_hz: 400,
+};
+const FILENAME = 'vad_config.json';
+function configRoot() {
+    return process.env['YF_CONFIG_DIR']
+        ?? path.join(process.env['HOME'] || process.env['USERPROFILE'] || os.homedir(), '.yujin-forge');
+}
+function configPath() {
+    return path.join(configRoot(), FILENAME);
+}
+function clamp(n, lo, hi) {
+    if (typeof n !== 'number' || !Number.isFinite(n))
+        return lo;
+    return Math.max(lo, Math.min(hi, n));
+}
+/** Validate + sanitize a config payload coming from disk or panel. */
+export function sanitiseVadConfig(input) {
+    const o = (input && typeof input === 'object') ? input : {};
+    const engine = o['engine'] === 'freq-band' ? 'freq-band' : 'amplitude';
+    return {
+        engine,
+        baseline_ms: clamp(Number(o['baseline_ms'] ?? DEFAULT_VAD_CONFIG.baseline_ms), 100, 5_000),
+        threshold_mult: clamp(Number(o['threshold_mult'] ?? DEFAULT_VAD_CONFIG.threshold_mult), 1.0, 10.0),
+        min_threshold: clamp(Number(o['min_threshold'] ?? DEFAULT_VAD_CONFIG.min_threshold), 0.001, 0.5),
+        max_threshold: clamp(Number(o['max_threshold'] ?? DEFAULT_VAD_CONFIG.max_threshold), 0.005, 0.8),
+        silence_ms: clamp(Number(o['silence_ms'] ?? DEFAULT_VAD_CONFIG.silence_ms), 200, 10_000),
+        min_voiced_ms: clamp(Number(o['min_voiced_ms'] ?? DEFAULT_VAD_CONFIG.min_voiced_ms), 50, 2_000),
+        tick_ms: clamp(Number(o['tick_ms'] ?? DEFAULT_VAD_CONFIG.tick_ms), 20, 500),
+        debug_overlay: o['debug_overlay'] === true,
+        session_stats: o['session_stats'] === true,
+        freq_low_hz: clamp(Number(o['freq_low_hz'] ?? DEFAULT_VAD_CONFIG.freq_low_hz), 20, 1_000),
+        freq_high_hz: clamp(Number(o['freq_high_hz'] ?? DEFAULT_VAD_CONFIG.freq_high_hz), 100, 4_000),
+    };
+}
+export async function readVadConfig() {
+    try {
+        const raw = await fs.readFile(configPath(), 'utf-8');
+        return sanitiseVadConfig(JSON.parse(raw));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { ...DEFAULT_VAD_CONFIG };
+        /* Corrupt file: behave as default; the next write overwrites. */
+        return { ...DEFAULT_VAD_CONFIG };
+    }
+}
+export async function writeVadConfig(cfg) {
+    const clean = sanitiseVadConfig(cfg);
+    const f = configPath();
+    await fs.mkdir(path.dirname(f), { recursive: true });
+    const tmp = f + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify(clean, null, 2), 'utf-8');
+    await renameWithRetry(tmp, f);
+}
+/** Append a VAD session-stats row to ~/.yujin-forge/vad_sessions.jsonl. */
+export async function appendVadSessionStats(row) {
+    const f = path.join(configRoot(), 'vad_sessions.jsonl');
+    await fs.mkdir(path.dirname(f), { recursive: true });
+    const line = JSON.stringify({ ts: new Date().toISOString(), ...row }) + '\n';
+    await fs.appendFile(f, line, 'utf-8');
+}
+//# sourceMappingURL=vad_config.js.map

package/dist/core/vad_config.js.map

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

package/dist/core/whats_new.d.ts

@@ -0,0 +1,42 @@
+export interface WhatsNewEntry {
+    version: string;
+    date: string;
+    summary: string;
+    bullets: string[];
+}
+export declare const CATALOG: WhatsNewEntry[];
+export interface WhatsNewResult {
+    current_version: string;
+    last_seen_version: string | null;
+    entries: WhatsNewEntry[];
+}
+declare function lastSeenPath(): string;
+export declare function readLastSeen(): Promise<string | null>;
+export declare function writeLastSeen(version: string): Promise<void>;
+/**
+ * Parse a semver-ish version into a comparable tuple.
+ * "0.2.0-alpha.59k" -> [0, 2, 0, "alpha", 59, "k"]
+ * Releases without prerelease ("1.0.0") sort AFTER any prerelease
+ * of the same base.
+ */
+export declare function parseVersion(v: string): {
+    base: [number, number, number];
+    preLabel: string | null;
+    preNum: number;
+    preTail: string;
+};
+/** Returns negative when a < b, positive when a > b, 0 when equal. */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Returns the cumulative list of WhatsNewEntry that the user has
+ * not seen yet. Entries strictly greater than last_seen and
+ * <= current_version. When last_seen is null, returns the latest
+ * entry only (avoid wall-of-text on a fresh install).
+ */
+export declare function computeWhatsNew(currentVersion: string): Promise<WhatsNewResult>;
+/** Test seam. */
+export declare const _internal: {
+    lastSeenPath: typeof lastSeenPath;
+};
+export {};
+//# sourceMappingURL=whats_new.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"whats_new.d.ts","sourceRoot":"","sources":["../../src/core/whats_new.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAK,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAID,eAAO,MAAM,OAAO,EAAE,aAAa,EAqFlC,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,iBAAS,YAAY,IAAI,MAAM,CAI9B;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQ3D;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMlE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG;IACvC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAI,MAAM,CAAC;IACjB,OAAO,EAAG,MAAM,CAAC;CAClB,CAaA;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAoB5D;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,cAAc,CAAC,CAqBzB;AAED,iBAAiB;AACjB,eAAO,MAAM,SAAS;;CAAmB,CAAC"}