@nac3/forge-cli 0.2.0-alpha.4 → 0.2.0-alpha.59z.118

package/dist/core/incomplete_detector.js

@@ -0,0 +1,140 @@
+/**
+ * incomplete_detector.ts -- detects when an eco-tier reply looks
+ * confused / refused / truncated, so handleChat can escalate the
+ * turn to frontier without surfacing the bad reply to the user
+ * (alpha.57).
+ *
+ * The trigger is conservative on purpose. False positives mean
+ * we burn a frontier call when eco was fine; false negatives
+ * mean the user sees Gemini Lite's confused reply. We err on the
+ * "escalate" side only when there is a clear signal.
+ *
+ * Signals scanned:
+ *
+ *   1. Hallucinated-error phrases ("error de mapeo", "tuve un
+ *      error en el workflow", "i had an internal error",
+ *      "perdon, hubo un problema").
+ *   2. Refuse / dodge phrases ("no tengo suficiente informacion",
+ *      "necesito mas contexto para responder", "i need more
+ *      context to help with this", "no puedo procesar este
+ *      pedido", "no puedo ayudarte con eso").
+ *   3. Tool-round errors: any tool_round with is_error=true
+ *      whose error message looks like a schema / args failure
+ *      (typical Gemini misfire). NOT every tool error -- those
+ *      can be legitimate.
+ *   4. Length-vs-complexity mismatch: user prompt >= 120 chars
+ *      AND reply <= 60 chars AND no tool was called. That
+ *      signature reliably catches "I do not understand" replies.
+ *
+ * Output: { incomplete, signals[] }. The caller decides whether
+ * to escalate (it must also check the frontier budget cap).
+ *
+ * Cap: incomplete_detector runs ONLY when the served tier was
+ * eco. We never auto-escalate frontier -> something else.
+ *
+ * ASCII-only.
+ */
+/* All patterns are normalised to lowercase + accent-stripped
+ *  before matching. */
+function norm(s) {
+    return (s || '').normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+}
+/* Specific hallucinated-error phrases we have seen Gemini Lite
+ *  emit when it loses the workflow context. */
+const HALLUCINATED_ERRORS = [
+    'error de mapeo',
+    'tuve un error',
+    'i had an internal error',
+    'hubo un problema',
+    'perdon, hubo un problema',
+    'perdon, tuve',
+    'me equivoque al',
+    'voy a corregir el registro',
+    'tuve un error de mapeo',
+    'tuve un fallo',
+    'something went wrong on my side',
+    'i ran into an issue processing',
+];
+/* Refuse / dodge patterns -- the assistant is asking for more
+ *  context instead of using what's already in the conversation. */
+const REFUSE_DODGE = [
+    'necesito mas contexto',
+    'necesito mas informacion',
+    'no tengo suficiente informacion',
+    'no tengo suficiente contexto',
+    'i need more context',
+    'i need additional context',
+    'i do not have enough context',
+    'i do not have enough information',
+    'no puedo procesar este pedido',
+    'no puedo procesar el pedido',
+    'no puedo ayudarte con eso',
+    'i cannot help with this',
+    'i am unable to process',
+];
+function findPhrase(haystack, patterns) {
+    for (const p of patterns) {
+        if (haystack.includes(p))
+            return p;
+    }
+    return null;
+}
+export function detectIncomplete(input) {
+    const signals = [];
+    const userN = norm(input.user_text || '');
+    const replyN = norm(input.reply_text || '');
+    /* 1. Hallucinated errors. */
+    const err = findPhrase(replyN, HALLUCINATED_ERRORS);
+    if (err)
+        signals.push('hallucinated_error[' + err + ']');
+    /* 2. Refuse / dodge. */
+    const dodge = findPhrase(replyN, REFUSE_DODGE);
+    if (dodge)
+        signals.push('refuse_dodge[' + dodge + ']');
+    /* 3. Tool-round error fingerprints. */
+    const rounds = Array.isArray(input.tool_rounds) ? input.tool_rounds : [];
+    let schemaErrors = 0;
+    for (const r of rounds) {
+        if (!r || r.is_error !== true)
+            continue;
+        const result = r.result;
+        let resultText = '';
+        if (typeof result === 'string')
+            resultText = result;
+        else if (result && typeof result === 'object') {
+            try {
+                resultText = JSON.stringify(result);
+            }
+            catch {
+                resultText = '';
+            }
+        }
+        const rn = norm(resultText);
+        if (rn.includes('schema') || rn.includes('invalid args') || rn.includes('required field')
+            || rn.includes('expected') || rn.includes('unknown property')
+            || rn.includes('verb not found') || rn.includes('unknown verb_id')) {
+            schemaErrors += 1;
+        }
+    }
+    if (schemaErrors > 0)
+        signals.push('schema_errors[' + schemaErrors + ']');
+    /* 4. Length-vs-complexity mismatch (NO tool calls + tiny reply
+     *  + long user prompt). Calls are NOT counted as the user
+     *  prompt is the new turn, not the entire history.
+     *
+     *  Why no tool calls: if eco invoked a tool successfully + the
+     *  short reply just says "ok" / "listo", that is fine. The
+     *  problem case is when eco produced a tiny "I cannot do this"
+     *  text reply with no work behind it. */
+    const userLen = (input.user_text || '').length;
+    const replyLen = (input.reply_text || '').length;
+    const usedTools = rounds.length > 0;
+    if (!usedTools && userLen >= 120 && replyLen <= 60) {
+        signals.push('length_mismatch[user=' + userLen + ',reply=' + replyLen + ']');
+    }
+    return {
+        incomplete: signals.length > 0,
+        signals,
+    };
+}
+//# sourceMappingURL=incomplete_detector.js.map

package/dist/core/incomplete_detector.js.map

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

package/dist/core/learnings_client.d.ts

@@ -0,0 +1,104 @@
+/**
+ * F103 HITO 6.2 + 6.3 -- CLI client for the server-side lessons +
+ * doctrines worker.
+ *
+ * Three responsibilities:
+ *   1. Fetch /v1/lessons/active + /v1/doctrines/active from the
+ *      worker on demand.
+ *   2. Cache the responses locally for 5 min to avoid hammering
+ *      the worker on every system-prompt rebuild.
+ *   3. Fall back gracefully:
+ *      a. Worker unreachable -> stale cache (if any) -> embedded
+ *         fallback in dist/docs/doctrine/*.md.
+ *      b. Lessons -- no embedded fallback exists; if both worker
+ *         and cache fail, return empty array (CLI keeps working,
+ *         just without server-side lessons).
+ *
+ * Why local cache aggressive: the system prompt is rebuilt on
+ * every chat turn. Without cache, every turn would HTTP to the
+ * worker, adding ~100-300ms of latency. 5-min cache amortises.
+ *
+ * Why offline fallback: Forge must keep working when the worker
+ * is down. Doctrines have an embedded fallback in dist/. Lessons
+ * are an additive layer; missing them degrades gracefully.
+ *
+ * Cache shape:
+ *   ~/.yujin-forge/cache/lessons.json
+ *   ~/.yujin-forge/cache/doctrines.json
+ *
+ * Each file has { fetched_at: <unix ms>, payload: <server body> }.
+ *
+ * ASCII-only.
+ */
+export interface LessonRow {
+    slug: string;
+    rule_text: string;
+    scenario_json: string;
+    status: 'proposed' | 'active' | 'demoted' | 'archived';
+    evidence_count: number;
+    hit_count: number;
+    last_hit_at: string | null;
+    proposed_at: string;
+    promoted_at: string | null;
+    demoted_at: string | null;
+    rejection_reason: string | null;
+    min_cli_version: string;
+    proposed_by_handle_hash: string;
+    conflicts_with_json: string;
+}
+export interface DoctrineSummary {
+    slug: string;
+    version: number;
+    min_cli_version: string;
+}
+interface CacheEnvelope<T> {
+    fetched_at: number;
+    payload: T;
+    worker_url: string;
+}
+declare function cacheDir(): string;
+declare function workerBaseUrl(): string;
+declare function readCache<T>(file: string): Promise<CacheEnvelope<T> | null>;
+declare function writeCache<T>(file: string, envelope: CacheEnvelope<T>): Promise<void>;
+declare function isFresh(env: CacheEnvelope<unknown>): boolean;
+declare function isStale(env: CacheEnvelope<unknown>): boolean;
+/** Fetch the active lessons from the worker (cached 5 min locally).
+ *  Returns [] if the worker is unreachable AND no stale cache
+ *  exists -- the CLI keeps working, just without lessons. */
+export declare function fetchActiveLessons(opts?: {
+    force?: boolean;
+}): Promise<LessonRow[]>;
+/** Fetch a specific lesson by slug (for demoted lessons accessed
+ *  via yujin.doctrine.discover(learnings/<slug>)). No local cache --
+ *  these are infrequent + always go to the worker. */
+export declare function fetchLessonBySlug(slug: string): Promise<LessonRow | null>;
+/** Report an anonymized hit. Fire-and-forget; failures swallowed.
+ *  Drives LRU eviction on the server side. */
+export declare function reportLessonHit(slug: string): Promise<void>;
+/** Fetch the list of active doctrine slugs + their versions.
+ *  Falls back to the local dist/docs/doctrine/*.md filename list
+ *  when the worker is unreachable. */
+export declare function fetchActiveDoctrines(): Promise<DoctrineSummary[]>;
+/** Fetch the markdown body of a specific doctrine. Worker first,
+ *  filesystem fallback. */
+export declare function fetchDoctrineBySlug(slug: string): Promise<string | null>;
+/** Build the GLOBAL LEARNINGS section to inject into the system
+ *  prompt. Returns empty string when:
+ *   - There are no active lessons.
+ *   - The token budget is exhausted before any lesson fits.
+ *
+ *  Token estimation uses a 4-chars-per-token heuristic; close
+ *  enough for the budget cap. */
+export declare function buildGlobalLearningsSection(opts?: {
+    maxTokens?: number;
+}): Promise<string>;
+export declare const _internal: {
+    cacheDir: typeof cacheDir;
+    workerBaseUrl: typeof workerBaseUrl;
+    readCache: typeof readCache;
+    writeCache: typeof writeCache;
+    isFresh: typeof isFresh;
+    isStale: typeof isStale;
+};
+export {};
+//# sourceMappingURL=learnings_client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"learnings_client.d.ts","sourceRoot":"","sources":["../../src/core/learnings_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAWH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;IACvD,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,uBAAuB,EAAE,MAAM,CAAC;IAChC,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,aAAa,CAAC,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,iBAAS,QAAQ,IAAI,MAAM,CAE1B;AAED,iBAAS,aAAa,IAAI,MAAM,CAI/B;AAMD,iBAAe,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAO1E;AAED,iBAAe,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAOpF;AAED,iBAAS,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,OAAO,CAErD;AAED,iBAAS,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,OAAO,CAErD;AAMD;;6DAE6D;AAC7D,wBAAsB,kBAAkB,CAAC,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CA6B7F;AAED;;sDAEsD;AACtD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAU/E;AAED;8CAC8C;AAC9C,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASjE;AAMD;;sCAEsC;AACtC,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAyBvE;AAED;2BAC2B;AAC3B,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAa9E;AA2BD;;;;;;iCAMiC;AACjC,wBAAsB,2BAA2B,CAAC,IAAI,GAAE;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BvB;AAMD,eAAO,MAAM,SAAS;;;;;;;CAErB,CAAC"}

package/dist/core/learnings_client.js

@@ -0,0 +1,262 @@
+/**
+ * F103 HITO 6.2 + 6.3 -- CLI client for the server-side lessons +
+ * doctrines worker.
+ *
+ * Three responsibilities:
+ *   1. Fetch /v1/lessons/active + /v1/doctrines/active from the
+ *      worker on demand.
+ *   2. Cache the responses locally for 5 min to avoid hammering
+ *      the worker on every system-prompt rebuild.
+ *   3. Fall back gracefully:
+ *      a. Worker unreachable -> stale cache (if any) -> embedded
+ *         fallback in dist/docs/doctrine/*.md.
+ *      b. Lessons -- no embedded fallback exists; if both worker
+ *         and cache fail, return empty array (CLI keeps working,
+ *         just without server-side lessons).
+ *
+ * Why local cache aggressive: the system prompt is rebuilt on
+ * every chat turn. Without cache, every turn would HTTP to the
+ * worker, adding ~100-300ms of latency. 5-min cache amortises.
+ *
+ * Why offline fallback: Forge must keep working when the worker
+ * is down. Doctrines have an embedded fallback in dist/. Lessons
+ * are an additive layer; missing them degrades gracefully.
+ *
+ * Cache shape:
+ *   ~/.yujin-forge/cache/lessons.json
+ *   ~/.yujin-forge/cache/doctrines.json
+ *
+ * Each file has { fetched_at: <unix ms>, payload: <server body> }.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { VERSION } from '../version.js';
+const CACHE_DIR_NAME = '.yujin-forge';
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const STALE_TTL_MS = 24 * 60 * 60 * 1000; // 24h -- after this, stale cache is ignored even on worker failure
+function cacheDir() {
+    return path.join(homedir(), CACHE_DIR_NAME, 'cache');
+}
+function workerBaseUrl() {
+    return process.env.YUJIN_WORKER_URL
+        || process.env.YF_WORKER_URL
+        || 'https://yujin-hito4.yujinapp.workers.dev';
+}
+async function ensureCacheDir() {
+    await fs.mkdir(cacheDir(), { recursive: true });
+}
+async function readCache(file) {
+    try {
+        const raw = await fs.readFile(path.join(cacheDir(), file), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeCache(file, envelope) {
+    try {
+        await ensureCacheDir();
+        await fs.writeFile(path.join(cacheDir(), file), JSON.stringify(envelope, null, 2), 'utf-8');
+    }
+    catch {
+        /* swallow -- cache is best-effort */
+    }
+}
+function isFresh(env) {
+    return Date.now() - env.fetched_at < CACHE_TTL_MS;
+}
+function isStale(env) {
+    return Date.now() - env.fetched_at < STALE_TTL_MS;
+}
+/* ===================================================================
+ * Lessons
+ * ================================================================ */
+/** Fetch the active lessons from the worker (cached 5 min locally).
+ *  Returns [] if the worker is unreachable AND no stale cache
+ *  exists -- the CLI keeps working, just without lessons. */
+export async function fetchActiveLessons(opts = {}) {
+    const cached = await readCache('lessons.json');
+    if (!opts.force && cached && isFresh(cached)) {
+        return cached.payload.lessons || [];
+    }
+    const url = workerBaseUrl() + '/v1/lessons/active';
+    try {
+        const r = await fetch(url, {
+            headers: { 'x-yf-cli-version': VERSION },
+        });
+        if (!r.ok) {
+            /* Worker reachable but error. Fall back to cache if stale-OK. */
+            if (cached && isStale(cached))
+                return cached.payload.lessons || [];
+            return [];
+        }
+        const body = await r.json();
+        if (!body.ok) {
+            if (cached && isStale(cached))
+                return cached.payload.lessons || [];
+            return [];
+        }
+        await writeCache('lessons.json', {
+            fetched_at: Date.now(), payload: { lessons: body.lessons }, worker_url: url,
+        });
+        return body.lessons || [];
+    }
+    catch {
+        /* Network failure. Fall back to stale cache if any. */
+        if (cached && isStale(cached))
+            return cached.payload.lessons || [];
+        return [];
+    }
+}
+/** Fetch a specific lesson by slug (for demoted lessons accessed
+ *  via yujin.doctrine.discover(learnings/<slug>)). No local cache --
+ *  these are infrequent + always go to the worker. */
+export async function fetchLessonBySlug(slug) {
+    const url = workerBaseUrl() + '/v1/lessons/by-slug/' + encodeURIComponent(slug);
+    try {
+        const r = await fetch(url, { headers: { 'x-yf-cli-version': VERSION } });
+        if (!r.ok)
+            return null;
+        const body = await r.json();
+        return body.ok ? body.lesson : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Report an anonymized hit. Fire-and-forget; failures swallowed.
+ *  Drives LRU eviction on the server side. */
+export async function reportLessonHit(slug) {
+    const url = workerBaseUrl() + '/v1/lessons/hit/' + encodeURIComponent(slug);
+    try {
+        await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'x-yf-cli-version': VERSION },
+            body: '{}',
+        });
+    }
+    catch { /* swallow -- telemetry is best-effort */ }
+}
+/* ===================================================================
+ * Doctrines
+ * ================================================================ */
+/** Fetch the list of active doctrine slugs + their versions.
+ *  Falls back to the local dist/docs/doctrine/*.md filename list
+ *  when the worker is unreachable. */
+export async function fetchActiveDoctrines() {
+    const cached = await readCache('doctrines.json');
+    if (cached && isFresh(cached)) {
+        return cached.payload.doctrines || [];
+    }
+    const url = workerBaseUrl() + '/v1/doctrines/active';
+    try {
+        const r = await fetch(url, { headers: { 'x-yf-cli-version': VERSION } });
+        if (!r.ok) {
+            if (cached && isStale(cached))
+                return cached.payload.doctrines || [];
+            return localDoctrineFallback();
+        }
+        const body = await r.json();
+        if (!body.ok) {
+            if (cached && isStale(cached))
+                return cached.payload.doctrines || [];
+            return localDoctrineFallback();
+        }
+        await writeCache('doctrines.json', {
+            fetched_at: Date.now(), payload: { doctrines: body.doctrines }, worker_url: url,
+        });
+        return body.doctrines || [];
+    }
+    catch {
+        if (cached && isStale(cached))
+            return cached.payload.doctrines || [];
+        return localDoctrineFallback();
+    }
+}
+/** Fetch the markdown body of a specific doctrine. Worker first,
+ *  filesystem fallback. */
+export async function fetchDoctrineBySlug(slug) {
+    const url = workerBaseUrl() + '/v1/doctrines/by-slug/' + encodeURIComponent(slug);
+    try {
+        const r = await fetch(url, { headers: { 'x-yf-cli-version': VERSION } });
+        if (r.ok) {
+            const body = await r.json();
+            if (body.ok && body.doctrine && typeof body.doctrine.content_md === 'string') {
+                return body.doctrine.content_md;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    /* Filesystem fallback. */
+    return readLocalDoctrine(slug);
+}
+async function readLocalDoctrine(slug) {
+    /* Resolve from dist/docs/doctrine/ relative to this file. */
+    const candidates = [
+        path.resolve(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1')), '..', '..', 'docs', 'doctrine', slug + '.md'),
+        path.resolve(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1')), '..', '..', '..', 'docs', 'doctrine', slug + '.md'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            return await fs.readFile(candidate, 'utf-8');
+        }
+        catch { /* try next */ }
+    }
+    return null;
+}
+async function localDoctrineFallback() {
+    /* When the worker is unreachable, return the slugs we know about
+     * from the dist filesystem. version = 0 indicates fallback. */
+    const KNOWN = ['workflow', 'yf-commands', 'gates', 'nac3-attrs', 'pizarron', 'r8-modal', 'g-doc'];
+    return KNOWN.map((slug) => ({ slug, version: 0, min_cli_version: '0.0.0' }));
+}
+/* ===================================================================
+ * HITO 6.3 -- prompt section builder
+ * ================================================================ */
+/** Build the GLOBAL LEARNINGS section to inject into the system
+ *  prompt. Returns empty string when:
+ *   - There are no active lessons.
+ *   - The token budget is exhausted before any lesson fits.
+ *
+ *  Token estimation uses a 4-chars-per-token heuristic; close
+ *  enough for the budget cap. */
+export async function buildGlobalLearningsSection(opts = {}) {
+    const maxTokens = opts.maxTokens ?? 2000;
+    const lessons = await fetchActiveLessons();
+    if (lessons.length === 0)
+        return '';
+    const parts = [];
+    parts.push('=================================================================');
+    parts.push('GLOBAL LEARNINGS (server-managed, promoted by admin)');
+    parts.push('=================================================================');
+    parts.push('');
+    parts.push('These rules are active for every Forge user. They came from');
+    parts.push('the brain matrix scenarios that validated each pattern.');
+    parts.push('');
+    let usedChars = parts.join('\n').length;
+    const maxChars = maxTokens * 4;
+    let injected = 0;
+    for (const lesson of lessons) {
+        const block = '* ' + lesson.slug + ': ' + lesson.rule_text + '\n';
+        if (usedChars + block.length > maxChars)
+            break;
+        parts.push(block);
+        usedChars += block.length;
+        injected++;
+    }
+    if (injected === 0)
+        return '';
+    parts.push('');
+    return parts.join('\n');
+}
+/* ===================================================================
+ * Internal exports for tests
+ * ================================================================ */
+export const _internal = {
+    cacheDir, workerBaseUrl, readCache, writeCache, isFresh, isStale,
+};
+//# sourceMappingURL=learnings_client.js.map

package/dist/core/learnings_client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings_client.js","sourceRoot":"","sources":["../../src/core/learnings_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,MAAM,cAAc,GAAG,cAAc,CAAC;AACtC,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAE,YAAY;AACjD,MAAM,YAAY,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,mEAAmE;AA+B7G,SAAS,QAAQ;IACf,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC;AACvD,CAAC;AAED,SAAS,aAAa;IACpB,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB;WAC5B,OAAO,CAAC,GAAG,CAAC,aAAa;WACzB,0CAA0C,CAAC;AACpD,CAAC;AAED,KAAK,UAAU,cAAc;IAC3B,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAClD,CAAC;AAED,KAAK,UAAU,SAAS,CAAI,IAAY;IACtC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QACpE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAqB,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,UAAU,CAAI,IAAY,EAAE,QAA0B;IACnE,IAAI,CAAC;QACH,MAAM,cAAc,EAAE,CAAC;QACvB,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC9F,CAAC;IAAC,MAAM,CAAC;QACP,qCAAqC;IACvC,CAAC;AACH,CAAC;AAED,SAAS,OAAO,CAAC,GAA2B;IAC1C,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,UAAU,GAAG,YAAY,CAAC;AACpD,CAAC;AAED,SAAS,OAAO,CAAC,GAA2B;IAC1C,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,UAAU,GAAG,YAAY,CAAC;AACpD,CAAC;AAED;;sEAEsE;AAEtE;;6DAE6D;AAC7D,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAA4B,EAAE;IACrE,MAAM,MAAM,GAAG,MAAM,SAAS,CAA2B,cAAc,CAAC,CAAC;IACzE,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7C,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACtC,CAAC;IACD,MAAM,GAAG,GAAG,aAAa,EAAE,GAAG,oBAAoB,CAAC;IACnD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YACzB,OAAO,EAAE,EAAE,kBAAkB,EAAE,OAAO,EAAE;SACzC,CAAC,CAAC;QACH,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACV,iEAAiE;YACjE,IAAI,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;gBAAE,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;YACnE,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,IAAI,EAA2C,CAAC;QACrE,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,IAAI,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;gBAAE,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;YACnE,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,UAAU,CAAC,cAAc,EAAE;YAC/B,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,GAAG;SAC5E,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,uDAAuD;QACvD,IAAI,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QACnE,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;sDAEsD;AACtD,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAY;IAClD,MAAM,GAAG,GAAG,aAAa,EAAE,GAAG,sBAAsB,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAChF,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,kBAAkB,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;QACzE,IAAI,CAAC,CAAC,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QACvB,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,IAAI,EAAwC,CAAC;QAClE,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;8CAC8C;AAC9C,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY;IAChD,MAAM,GAAG,GAAG,aAAa,EAAE,GAAG,kBAAkB,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAC5E,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,GAAG,EAAE;YACf,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,OAAO,EAAE;YAC5E,IAAI,EAAE,IAAI;SACX,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC,CAAC,yCAAyC,CAAC,CAAC;AACvD,CAAC;AAED;;sEAEsE;AAEtE;;sCAEsC;AACtC,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,MAAM,MAAM,GAAG,MAAM,SAAS,CAAmC,gBAAgB,CAAC,CAAC;IACnF,IAAI,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9B,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;IACxC,CAAC;IACD,MAAM,GAAG,GAAG,aAAa,EAAE,GAAG,sBAAsB,CAAC;IACrD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,kBAAkB,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;QACzE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACV,IAAI,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;gBAAE,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;YACrE,OAAO,qBAAqB,EAAE,CAAC;QACjC,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,IAAI,EAAmD,CAAC;QAC7E,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,IAAI,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;gBAAE,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;YACrE,OAAO,qBAAqB,EAAE,CAAC;QACjC,CAAC;QACD,MAAM,UAAU,CAAC,gBAAgB,EAAE;YACjC,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,UAAU,EAAE,GAAG;SAChF,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;QACrE,OAAO,qBAAqB,EAAE,CAAC;IACjC,CAAC;AACH,CAAC;AAED;2BAC2B;AAC3B,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAAY;IACpD,MAAM,GAAG,GAAG,aAAa,EAAE,GAAG,wBAAwB,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAClF,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,kBAAkB,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;QACzE,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC;YACT,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,IAAI,EAAuD,CAAC;YACjF,IAAI,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,QAAQ,IAAI,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;gBAC7E,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC;YAClC,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;IAC9B,0BAA0B;IAC1B,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,IAAY;IAC3C,6DAA6D;IAC7D,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,GAAG,KAAK,CAAC;QACxI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,GAAG,KAAK,CAAC;KAC/I,CAAC;IACF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC;QAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,KAAK,UAAU,qBAAqB;IAClC;mEAC+D;IAC/D,MAAM,KAAK,GAAG,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IAClG,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED;;sEAEsE;AAEtE;;;;;;iCAMiC;AACjC,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,OAE9C,EAAE;IACJ,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC;IACzC,MAAM,OAAO,GAAG,MAAM,kBAAkB,EAAE,CAAC;IAC3C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,mEAAmE,CAAC,CAAC;IAChF,KAAK,CAAC,IAAI,CAAC,sDAAsD,CAAC,CAAC;IACnE,KAAK,CAAC,IAAI,CAAC,mEAAmE,CAAC,CAAC;IAChF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAC;IAC1E,KAAK,CAAC,IAAI,CAAC,yDAAyD,CAAC,CAAC;IACtE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,IAAI,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;IACxC,MAAM,QAAQ,GAAG,SAAS,GAAG,CAAC,CAAC;IAC/B,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC;QAClE,IAAI,SAAS,GAAG,KAAK,CAAC,MAAM,GAAG,QAAQ;YAAE,MAAM;QAC/C,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClB,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC;QAC1B,QAAQ,EAAE,CAAC;IACb,CAAC;IAED,IAAI,QAAQ,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC9B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;sEAEsE;AAEtE,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO;CACjE,CAAC"}

package/dist/core/limits_config.d.ts

@@ -0,0 +1,76 @@
+export type ToolRoundsFamily = 'default' | 'reader_family' | 'search_family' | 'writer_family';
+export interface MaxToolRoundsConfig {
+    default: number;
+    reader_family: number;
+    search_family: number;
+    writer_family: number;
+    /** alpha.59e -- ceiling used when Danger Zone auto-approve
+     *  is ON. Lets the LLM run long chains of verbs without
+     *  intervention when the user has explicitly opted in to
+     *  velocity-over-safety mode. */
+    autonomous: number;
+}
+export interface RequestTimeoutsConfig {
+    managed_proxy: number;
+    byok_anthropic: number;
+    byok_openai: number;
+    byok_gemini: number;
+}
+export interface ShellLimitsConfig {
+    /** Default timeout per shell invocation. */
+    timeout_ms_default: number;
+    /** Hard ceiling -- caller cannot override above this. */
+    timeout_ms_max: number;
+    /** Combined stdout + stderr max bytes; output beyond is
+     *  truncated with a marker. */
+    max_output_bytes: number;
+    /** When true, ANY cwd outside the project root forces an
+     *  approval prompt -- even for safe-bucket commands. Pablo's
+     *  Q2: escape-with-approval. */
+    cwd_boundary_strict: boolean;
+}
+export interface DangerZoneConfig {
+    /** When true, EVERY approval prompt is auto-approved + logged
+     *  with approval_mode='danger_zone_bypass'. Trade-off:
+     *  velocity over safety. */
+    auto_approve_all: boolean;
+}
+export interface LimitsConfig {
+    version: 1;
+    max_tool_rounds: MaxToolRoundsConfig;
+    request_timeout_ms: RequestTimeoutsConfig;
+    classifier_timeout_ms: number;
+    managed_max_tokens_per_turn: number;
+    shell: ShellLimitsConfig;
+    danger_zone: DangerZoneConfig;
+}
+export declare function defaultLimitsConfig(): LimitsConfig;
+/** Read the active config. Cached for ~3 seconds to avoid
+ *  hammering the FS on every router call. Use forceRefresh=true
+ *  in tests / CLI after a setValue. */
+export declare function readLimitsConfig(forceRefresh?: boolean): Promise<LimitsConfig>;
+export declare function writeLimitsConfig(cfg: LimitsConfig): Promise<void>;
+export declare function resetLimitsConfig(): Promise<LimitsConfig>;
+/** Reset the in-memory cache. Tests use this between specs. */
+export declare function _resetLimitsCache(): void;
+export declare function classifyVerbFamily(verbId: string): ToolRoundsFamily;
+/**
+ * Pick the max_tool_rounds limit for a turn based on the verb
+ * family the LLM is using. The family is derived from the
+ * FIRST nac3 verb the LLM emits in this turn -- once decided,
+ * the cap stays for the rest of the turn (no mid-turn shifts).
+ *
+ * Callers track the first verb invoked + pass it here.
+ */
+export declare function getMaxToolRoundsForFamily(cfg: MaxToolRoundsConfig, family: ToolRoundsFamily): number;
+/** All settable field paths in dotted notation, used by `yf
+ *  limits set <field> <value>`. */
+export declare const LIMITS_FIELD_PATHS: readonly string[];
+export declare function isLimitsFieldPath(p: string): boolean;
+export declare const LIMITS_BOOLEAN_FIELD_PATHS: readonly string[];
+export declare function isLimitsBooleanFieldPath(p: string): boolean;
+export declare function setLimitsBooleanField(field: string, value: boolean): Promise<LimitsConfig>;
+/** Apply a single setValue. Returns the updated config. Throws
+ *  on invalid path or non-numeric value. */
+export declare function setLimitsField(field: string, value: number): Promise<LimitsConfig>;
+//# sourceMappingURL=limits_config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"limits_config.d.ts","sourceRoot":"","sources":["../../src/core/limits_config.ts"],"names":[],"mappings":"AAqDA,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,eAAe,GAAG,eAAe,GAAG,eAAe,CAAC;AAE/F,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB;;;qCAGiC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAGD,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,cAAc,EAAE,MAAM,CAAC;IACvB;mCAC+B;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB;;oCAEgC;IAChC,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAGD,MAAM,WAAW,gBAAgB;IAC/B;;gCAE4B;IAC5B,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,CAAC,CAAC;IACX,eAAe,EAAE,mBAAmB,CAAC;IACrC,kBAAkB,EAAE,qBAAqB,CAAC;IAC1C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,2BAA2B,EAAE,MAAM,CAAC;IACpC,KAAK,EAAE,iBAAiB,CAAC;IACzB,WAAW,EAAE,gBAAgB,CAAC;CAC/B;AAED,wBAAgB,mBAAmB,IAAI,YAAY,CA4BlD;AA8DD;;uCAEuC;AACvC,wBAAsB,gBAAgB,CAAC,YAAY,UAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,CAalF;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CASxE;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,YAAY,CAAC,CAI/D;AAED,+DAA+D;AAC/D,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC;AAqBD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAMnE;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,mBAAmB,EACxB,MAAM,EAAE,gBAAgB,GACvB,MAAM,CAOR;AAID;mCACmC;AACnC,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAe/C,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEpD;AAID,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAGvD,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAgBhG;AAED;4CAC4C;AAC5C,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAkBxF"}