agent-nuvira 3.3.7 → 3.3.9

package/dist/learning/session-digest.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Session digest — the per-project memory of what RECENT ASKS did, across
+ * sessions (Phase 4 / G6, the DETERMINISTIC branch).
+ *
+ * WHY THIS EXISTS (and why it is not an LLM summary)
+ * ---------------------------------------------------
+ * Two continuity needs sit next to each other:
+ *   - `working-state.ts` remembers the WORK (files touched, verification debt,
+ *     user-reported regressions) but NOT what was ASKED or how it ended; and
+ *   - a cross-session "what happened recently" memory, which the plan flagged as
+ *     a possible LLM-compaction target.
+ *
+ * The plan left that second one as an OPEN DECISION (LLM summary vs deterministic).
+ * This module makes the DETERMINISTIC choice, deliberately:
+ *   - a model-written summary can assert "the build works" and re-introduce the
+ *     exact false-success class Parts 1/2 closed;
+ *   - a digest of FACTS (goal, outcome, tools, whether anything was verified)
+ *     cannot lie about completion because it does not judge it.
+ *
+ * So the digest is ADVISORY CONTEXT ONLY. It is never read to decide whether a
+ * step is done — completion still derives from artifacts on disk. A test pins
+ * that (a digest claiming success cannot flip a completion).
+ *
+ * Deterministic, LLM-free, best-effort (never throws), and bounded so it adds a
+ * fixed, small weight to the prompt.
+ */
+/** One finished turn, as recorded by the caller. */
+export interface SessionTurn {
+    /** Epoch ms the turn ended. */
+    at: number;
+    /** The ask, truncated. */
+    goal: string;
+    /** The turn's outcome kind (`acted` / `incomplete` / `failed` / `cancelled`). */
+    outcome: string;
+    /** Tools that ran (deduped, capped). */
+    tools: string[];
+    /** A verification tool ran successfully this turn. */
+    verified: boolean;
+}
+/** What a caller records when a turn ends. */
+export interface SessionTurnInput {
+    projectPath: string;
+    goal: string;
+    outcome: string;
+    tools?: readonly string[];
+    verified?: boolean;
+}
+export interface ProjectSessionDigest {
+    projectPath: string;
+    /** Newest last. */
+    turns: SessionTurn[];
+    updatedAt: number;
+}
+/** Cap on remembered turns per project (oldest drop first). */
+export declare const MAX_TURNS = 12;
+/** Cap on remembered tools per turn. */
+export declare const MAX_TOOLS_PER_TURN = 8;
+/** Cap on the goal text kept per turn. */
+export declare const MAX_GOAL_CHARS = 160;
+/** Cap on the rendered block — it rides in prompts, so it stays small. */
+export declare const MAX_BLOCK_CHARS = 1600;
+/**
+ * Record a finished turn and return the updated digest. Best-effort: never throws.
+ */
+export declare function recordSessionTurn(input: SessionTurnInput): ProjectSessionDigest;
+/** Read one project's digest, or null. */
+export declare function getSessionDigest(projectPath: string): ProjectSessionDigest | null;
+/**
+ * Format a project's digest as a bounded, model-readable block ('' when there is
+ * nothing to show — a clean project adds no prompt weight).
+ *
+ * ADVISORY ONLY: the header says outright that this is history, not a status —
+ * so a model cannot read an old "completed" line as proof the work is done now.
+ */
+export declare function formatSessionDigest(projectPath: string, now?: number): string;
+/** Forget one project's digest. */
+export declare function clearSessionDigest(projectPath: string): void;
+//# sourceMappingURL=session-digest.d.ts.map

package/dist/learning/session-digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-digest.d.ts","sourceRoot":"","sources":["../../src/learning/session-digest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,sDAAsD;IACtD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB;IACnB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAUD,+DAA+D;AAC/D,eAAO,MAAM,SAAS,KAAK,CAAC;AAC5B,wCAAwC;AACxC,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,0CAA0C;AAC1C,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,0EAA0E;AAC1E,eAAO,MAAM,eAAe,OAAQ,CAAC;AAmDrC;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,oBAAoB,CA8B/E;AAED,0CAA0C;AAC1C,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAMjF;AAYD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAqBzF;AAED,mCAAmC;AACnC,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAU5D"}

package/dist/learning/session-digest.js

@@ -0,0 +1,185 @@
+/**
+ * Session digest — the per-project memory of what RECENT ASKS did, across
+ * sessions (Phase 4 / G6, the DETERMINISTIC branch).
+ *
+ * WHY THIS EXISTS (and why it is not an LLM summary)
+ * ---------------------------------------------------
+ * Two continuity needs sit next to each other:
+ *   - `working-state.ts` remembers the WORK (files touched, verification debt,
+ *     user-reported regressions) but NOT what was ASKED or how it ended; and
+ *   - a cross-session "what happened recently" memory, which the plan flagged as
+ *     a possible LLM-compaction target.
+ *
+ * The plan left that second one as an OPEN DECISION (LLM summary vs deterministic).
+ * This module makes the DETERMINISTIC choice, deliberately:
+ *   - a model-written summary can assert "the build works" and re-introduce the
+ *     exact false-success class Parts 1/2 closed;
+ *   - a digest of FACTS (goal, outcome, tools, whether anything was verified)
+ *     cannot lie about completion because it does not judge it.
+ *
+ * So the digest is ADVISORY CONTEXT ONLY. It is never read to decide whether a
+ * step is done — completion still derives from artifacts on disk. A test pins
+ * that (a digest claiming success cannot flip a completion).
+ *
+ * Deterministic, LLM-free, best-effort (never throws), and bounded so it adds a
+ * fixed, small weight to the prompt.
+ */
+import { envBuff, resolveNuviraHome } from '../config/paths.js';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+// ─── Constants ──────────────────────────────────────────────────────────────
+const CURRENT_VERSION = 1;
+/** Cap on remembered turns per project (oldest drop first). */
+export const MAX_TURNS = 12;
+/** Cap on remembered tools per turn. */
+export const MAX_TOOLS_PER_TURN = 8;
+/** Cap on the goal text kept per turn. */
+export const MAX_GOAL_CHARS = 160;
+/** Cap on the rendered block — it rides in prompts, so it stays small. */
+export const MAX_BLOCK_CHARS = 1_600;
+/** Turns shown in the block (newest last). */
+const SHOWN_TURNS = 8;
+// ─── Storage ────────────────────────────────────────────────────────────────
+function memoryDir() {
+    return envBuff('MEMORY_DIR') || join(resolveNuviraHome(), 'memory');
+}
+function storePath() {
+    return join(memoryDir(), 'session-digests.json');
+}
+function normalizeProjectPath(projectPath) {
+    try {
+        return resolve(projectPath);
+    }
+    catch {
+        return projectPath;
+    }
+}
+function readFileSafe() {
+    try {
+        if (!existsSync(storePath()))
+            return { version: CURRENT_VERSION, projects: {} };
+        const data = JSON.parse(readFileSync(storePath(), 'utf-8'));
+        if (!data || typeof data !== 'object' || !data.projects || typeof data.projects !== 'object') {
+            return { version: CURRENT_VERSION, projects: {} };
+        }
+        return data;
+    }
+    catch {
+        return { version: CURRENT_VERSION, projects: {} };
+    }
+}
+function writeFileSafe(data) {
+    try {
+        if (!existsSync(memoryDir()))
+            mkdirSync(memoryDir(), { recursive: true });
+        writeFileSync(storePath(), JSON.stringify(data, null, 2), 'utf-8');
+    }
+    catch {
+        // Best-effort — a digest write must never break a turn.
+    }
+}
+function clip(text, max) {
+    const flat = (text || '').replace(/\s+/g, ' ').trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+// ─── API ────────────────────────────────────────────────────────────────────
+/**
+ * Record a finished turn and return the updated digest. Best-effort: never throws.
+ */
+export function recordSessionTurn(input) {
+    const projectPath = normalizeProjectPath(input.projectPath);
+    const now = Date.now();
+    try {
+        const data = readFileSafe();
+        const prev = data.projects[projectPath] ?? {
+            projectPath,
+            turns: [],
+            updatedAt: now,
+        };
+        const tools = [...new Set((input.tools ?? []).filter((t) => typeof t === 'string' && t))].slice(0, MAX_TOOLS_PER_TURN);
+        const turn = {
+            at: now,
+            goal: clip(input.goal, MAX_GOAL_CHARS),
+            outcome: clip(input.outcome || 'unknown', 24),
+            tools,
+            verified: input.verified === true,
+        };
+        const turns = [...prev.turns, turn];
+        if (turns.length > MAX_TURNS)
+            turns.splice(0, turns.length - MAX_TURNS);
+        const next = { projectPath, turns, updatedAt: now };
+        data.projects[projectPath] = next;
+        writeFileSafe(data);
+        return next;
+    }
+    catch {
+        return { projectPath, turns: [], updatedAt: now };
+    }
+}
+/** Read one project's digest, or null. */
+export function getSessionDigest(projectPath) {
+    try {
+        return readFileSafe().projects[normalizeProjectPath(projectPath)] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Relative age, spelled for a human reader. */
+function relativeAge(ts, now) {
+    const mins = Math.max(0, Math.round((now - ts) / 60_000));
+    if (mins < 1)
+        return 'just now';
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hours = Math.round(mins / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    return `${Math.round(hours / 24)}d ago`;
+}
+/**
+ * Format a project's digest as a bounded, model-readable block ('' when there is
+ * nothing to show — a clean project adds no prompt weight).
+ *
+ * ADVISORY ONLY: the header says outright that this is history, not a status —
+ * so a model cannot read an old "completed" line as proof the work is done now.
+ */
+export function formatSessionDigest(projectPath, now = Date.now()) {
+    try {
+        const digest = getSessionDigest(projectPath);
+        if (!digest || digest.turns.length === 0)
+            return '';
+        const shown = digest.turns.slice(-SHOWN_TURNS);
+        const lines = [
+            '[Recent sessions in THIS project — history for context only. This is NOT a status of the current work; verify artifacts on disk before assuming anything is done.]',
+        ];
+        for (const turn of shown) {
+            const verified = turn.verified ? ', verified' : '';
+            const tools = turn.tools.length > 0 ? ` (tools: ${turn.tools.join(', ')}${verified})` : verified ? ` (${verified.slice(2)})` : '';
+            lines.push(`• ${relativeAge(turn.at, now)} — ${turn.outcome}: "${turn.goal}"${tools}`);
+        }
+        let block = lines.join('\n');
+        if (block.length > MAX_BLOCK_CHARS) {
+            block = `${block.slice(0, MAX_BLOCK_CHARS)}\n[digest truncated to fit the context budget]`;
+        }
+        return block;
+    }
+    catch {
+        return '';
+    }
+}
+/** Forget one project's digest. */
+export function clearSessionDigest(projectPath) {
+    try {
+        const data = readFileSafe();
+        const key = normalizeProjectPath(projectPath);
+        if (!(key in data.projects))
+            return;
+        delete data.projects[key];
+        writeFileSafe(data);
+    }
+    catch {
+        // Best-effort.
+    }
+}
+//# sourceMappingURL=session-digest.js.map

package/dist/learning/session-digest.js.map

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

package/dist/learning/session-recall.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Session recall (Phase 4 follow-on) — SEMANTIC recall across past asks.
+ *
+ * WHY THIS EXISTS, AND WHY IT IS OPT-IN.
+ * The deterministic session digest (`session-digest.ts`) shows the LAST few asks
+ * in a project. That is good for continuity, but it is recency-based: an ask from
+ * three weeks ago about the SAME subject is invisible if ten unrelated asks
+ * happened since. This module adds *semantic* recall — embed each finished ask,
+ * and at the start of a new turn retrieve the past asks that mean the same thing,
+ * above an explicit cosine THRESHOLD, so relevance is by meaning rather than by
+ * a literal token overlap (`goalsLookSame`) or by recency.
+ *
+ * It is deliberately OFF unless asked for (`NUVIRA_SESSION_RECALL=1`). Semantics
+ * introduce an embedding dependency whose tiers can be slow to fail over; a
+ * feature that makes an ordinary turn wait on a model download would be a worse
+ * bug than the recall it buys. So, exactly like `--resume`, an ordinary run pays
+ * nothing: no read, no embed, no query.
+ *
+ * WHY IT CANNOT RE-OPEN FALSE SUCCESS. A recalled ask is HISTORY, presented as
+ * however it ENDED (`acted` / `incomplete` / `failed` / `cancelled`) — never as a
+ * completion the current work inherits. The block says so outright, and nothing
+ * here is read to decide whether a step is done: completion still derives from
+ * artifacts on disk. A recalled "the build works" is a sentence the past model
+ * wrote, quoted, not a fact the framework adopts.
+ *
+ * Bounded + best-effort throughout: a fixed entry cap, a fixed top-k, a fixed
+ * block size, and every read/write/embed wrapped so a corrupt index or a missing
+ * embedding tier degrades to "no recall", never a broken turn.
+ */
+/** The environment key that turns semantic recall on (`1`/`true`/`yes`). */
+export declare const SESSION_RECALL_ENV = "NUVIRA_SESSION_RECALL";
+/** Cosine floor a past ask must clear to be recalled (0-1). */
+export declare const DEFAULT_RECALL_THRESHOLD = 0.5;
+/** How many past asks to surface at most. */
+export declare const DEFAULT_RECALL_TOP_K = 3;
+/** Hard cap on the index (oldest dropped) — recall must never grow unbounded. */
+export declare const MAX_INDEX_ENTRIES = 500;
+/** Hard cap on the rendered block — it rides in prompts. */
+export declare const MAX_RECALL_BLOCK_CHARS = 1200;
+/** An embedding function (injectable for tests / deterministic callers). */
+export type EmbedFn = (text: string) => Promise<number[]>;
+/** One indexed past ask. */
+export interface RecallEntry {
+    id: string;
+    projectPath: string;
+    goal: string;
+    outcome: string;
+    savedAt: number;
+    vector: number[];
+}
+/** A recalled past ask with its similarity. */
+export interface RecallHit {
+    entry: RecallEntry;
+    similarity: number;
+}
+/**
+ * Is semantic recall on? DEFAULT ON — like checkpointing, an operator can turn
+ * it off, but a fresh install gets the feature rather than a switch that does
+ * nothing until someone reads the docs. `0`/`false`/`off`/`no` turn it off;
+ * unset (or any other value) leaves it ON.
+ */
+export declare function sessionRecallEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** The config/env shape a resolver reads (structural, so no import cycle). */
+export interface RecallConfigSource {
+    getAll(): {
+        memory?: {
+            sessionRecall?: boolean;
+        };
+    };
+}
+/**
+ * Resolve whether semantic recall is on, with the repo's precedence:
+ * an explicit FLAG wins, then the environment, then config, then the default
+ * (ON). This is the single place the decision is made, so the CLI, the loop and
+ * the dashboard cannot disagree.
+ */
+export declare function resolveSessionRecall(input?: {
+    flag?: boolean;
+    configManager?: RecallConfigSource | null;
+}): boolean;
+/**
+ * Index one finished ask for later semantic recall. Returns whether an entry was
+ * written. Best-effort and NO-OP when recall is off or embeddings are
+ * unavailable (a zero vector is never stored — it would only ever be a
+ * meaningless match).
+ */
+export declare function indexSessionTurn(input: {
+    projectPath: string;
+    goal: string;
+    outcome?: string;
+    savedAt?: number;
+}, opts?: {
+    embedFn?: EmbedFn;
+    force?: boolean;
+    enabled?: boolean;
+}): Promise<boolean>;
+/**
+ * The past asks semantically closest to `query`, above the threshold.
+ *
+ * `scope: 'project'` (default) limits recall to the current project directory —
+ * the same scoping the rest of the continuity stack uses, so a new task is not
+ * handed another project's history. `scope: 'all'` searches every project and
+ * names each hit's project in the block.
+ */
+export declare function recallPastSessions(query: string, opts?: {
+    projectPath?: string;
+    scope?: 'project' | 'all';
+    topK?: number;
+    threshold?: number;
+    embedFn?: EmbedFn;
+    force?: boolean;
+    enabled?: boolean;
+}): Promise<RecallHit[]>;
+/**
+ * Render recall hits as a bounded, model-readable block ('' when there are none).
+ *
+ * The header is load-bearing: it states that these are PAST asks — history for
+ * context only, NOT a status — so a recalled line cannot be read as proof the
+ * current work is done. Each hit carries how it ENDED and its project when the
+ * recall crossed projects.
+ */
+export declare function formatSessionRecall(hits: readonly RecallHit[], opts?: {
+    projectPath?: string;
+    now?: number;
+}): string;
+/**
+ * List every indexed past ask, newest first. Best-effort. The vectors are part of
+ * each entry; a caller that only needs a summary maps them away.
+ */
+export declare function listRecallEntries(): RecallEntry[];
+/** Remove one indexed past ask by id. Returns whether it was present. */
+export declare function removeRecallEntry(id: string): boolean;
+/** Remove the recall index (used by `nuvira retrieval clear`-style resets / tests). */
+export declare function clearSessionRecallIndex(): boolean;
+//# sourceMappingURL=session-recall.d.ts.map

package/dist/learning/session-recall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-recall.d.ts","sourceRoot":"","sources":["../../src/learning/session-recall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAeH,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,0BAA0B,CAAC;AAE1D,+DAA+D;AAC/D,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,6CAA6C;AAC7C,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,4DAA4D;AAC5D,eAAO,MAAM,sBAAsB,OAAQ,CAAC;AAE5C,4EAA4E;AAC5E,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAE1D,4BAA4B;AAC5B,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAOD,+CAA+C;AAC/C,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,WAAW,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AASD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAIlF;AASD,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,MAAM,IAAI;QAAE,MAAM,CAAC,EAAE;YAAE,aAAa,CAAC,EAAE,OAAO,CAAA;SAAE,CAAA;KAAE,CAAC;CACpD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAA;CAAO,GACxE,OAAO,CAMT;AAuED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,EAChF,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GACnE,OAAO,CAAC,OAAO,CAAC,CA2BlB;AAID;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;IACJ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACd,GACL,OAAO,CAAC,SAAS,EAAE,CAAC,CAqCtB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,SAAS,EAAE,EAC1B,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD,MAAM,CAiBR;AAgBD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,EAAE,CAEjD;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CASrD;AAED,uFAAuF;AACvF,wBAAgB,uBAAuB,IAAI,OAAO,CAQjD"}