@nexus-cortex/executors 4.26.0

package/dist/implementations/extensions/EndTurnTool.js

@@ -0,0 +1,172 @@
+/**
+ * EndTurn — generative end-of-turn attestation (Stage 1).
+ *
+ * Why: grounding/verification rules in system messages are ignored by some
+ * models (grok-4.3: ~0/6 on line-number fabrication); the SAME models obey
+ * tool mechanics (Edit `old_string`: 6/6). Routing the contract through a
+ * required tool converts an ignored request into an enforced checkpoint.
+ *
+ * The params are GENERATIVE, not multiple-choice: the model must re-derive
+ * each reference's verbatim source, paste the actual command output it saw,
+ * and write a skeptical self-review. A label can be rubber-stamped (Stage-1
+ * enum leaked 1/6); producing the evidence cannot — the act of
+ * reconstructing it forces the lookup and surfaces missed errors in latent
+ * space before the final message. Stage 1 does NOT verify server-side; it
+ * echoes the model's own self_review + sources back so it must act on them
+ * before finalizing. Server-side cross-check is Stage 2.
+ */
+import { BaseTool } from '../../base/index.js';
+export class EndTurnToolExecutor extends BaseTool {
+    constructor() {
+        super('EndTurn', 'End Turn', 'Mandatory final step before your user-facing answer. You must RECONSTRUCT the evidence for your work (not tick boxes): list each reference with the verbatim source you copied it from, paste real command output, and write a skeptical self-review.', {
+            type: 'object',
+            properties: {
+                citations: {
+                    type: 'array',
+                    description: "Every specific reference in your drafted answer (file:line, line numbers, URLs, API/function signatures, quotes). For EACH, give the exact token you transcribed from THIS turn's tool output. If you cannot produce the verbatim source, the reference is unverified — remove it from your answer and do not list it. Empty array = you cited none.",
+                    items: {
+                        type: 'object',
+                        properties: {
+                            reference: {
+                                type: 'string',
+                                description: 'The claim/reference as it appears in your answer.',
+                            },
+                            verbatim_source: {
+                                type: 'string',
+                                description: "The EXACT text copied from this turn's tool output that grounds it (a quoted code line, a URL from a fetched page). Character-for-character, like an edit old_string.",
+                            },
+                        },
+                        required: ['reference', 'verbatim_source'],
+                    },
+                },
+                verification: {
+                    type: 'array',
+                    description: 'Every verification command (build/test/lint) the task asked for that you actually ran THIS turn. Empty array = none asked. Do not list a command you did not run.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            command: { type: 'string', description: 'The command you ran.' },
+                            observed_result: {
+                                type: 'string',
+                                description: 'The actual result line you saw in this turn\'s tool output.',
+                            },
+                        },
+                        required: ['command', 'observed_result'],
+                    },
+                },
+                summary: {
+                    type: 'string',
+                    description: 'One sentence: what you delivered this turn.',
+                },
+                open_items: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Anything unverified, assumed, or incomplete. Empty array if nothing. Do not hide gaps.',
+                },
+                self_review: {
+                    type: 'string',
+                    description: 'Re-read your drafted answer as a skeptical reviewer. What did you NOT check? What is assumed or possibly wrong? What surface might you have missed? If you had one more tool call, what would you verify? Be specific — this pass exists to catch your own mistakes before they ship.',
+                },
+            },
+            // Only the two cheap, always-producible generative fields are required.
+            // The evidence arrays are legitimately empty on many turns ("empty =
+            // none"), so requiring them caused well-formed sparse attestations to
+            // loop-reject. Absent arrays normalize to [] in normalizeParams().
+            required: ['summary', 'self_review'],
+        });
+    }
+    /**
+     * Coerce a raw attestation into a well-formed shape. Absent arrays become []
+     * ("empty = none" per the field docs); malformed array items are dropped
+     * rather than rejected. This makes EndTurn non-blocking at the executor level
+     * — the strict, MEANINGFUL rejection (a verbatim_source not grounded in this
+     * turn's tool output) is enforced by the orchestrator's Stage-2 grounding
+     * check when CORTEX_ENDTURN_GATE is on, where it belongs. A blunt
+     * validate-and-reject here only produced retry loops that ended in the model
+     * giving up with NO attestation at all — strictly worse than a sparse one.
+     */
+    normalizeParams(params) {
+        const p = (params && typeof params === 'object' ? params : {});
+        // A citation is a (reference, verbatim_source) pair — drop any item missing
+        // either half (ungrounded evidence is not a citation). Same for verification.
+        const citations = (Array.isArray(p.citations) ? p.citations : [])
+            .filter((c) => c &&
+            typeof c.reference === 'string' &&
+            c.reference.trim() !== '' &&
+            typeof c.verbatim_source === 'string' &&
+            c.verbatim_source.trim() !== '')
+            .map((c) => ({ reference: c.reference, verbatim_source: c.verbatim_source }));
+        const verification = (Array.isArray(p.verification) ? p.verification : [])
+            .filter((v) => v &&
+            typeof v.command === 'string' &&
+            v.command.trim() !== '' &&
+            typeof v.observed_result === 'string' &&
+            v.observed_result.trim() !== '')
+            .map((v) => ({ command: v.command, observed_result: v.observed_result }));
+        const open_items = (Array.isArray(p.open_items) ? p.open_items : []).filter((o) => typeof o === 'string' && o.trim() !== '');
+        return {
+            citations,
+            verification,
+            summary: typeof p.summary === 'string' ? p.summary : '',
+            open_items,
+            self_review: typeof p.self_review === 'string' ? p.self_review : '',
+        };
+    }
+    validateToolParams(params) {
+        // Non-blocking: any object is acceptable. Missing/empty fields normalize
+        // (absent arrays → [], "empty = none"). The only thing worth a hard reject
+        // is a payload that isn't an object at all.
+        if (!params || typeof params !== 'object')
+            return 'params object required';
+        return null;
+    }
+    getDescription(params) {
+        const nCit = Array.isArray(params?.citations) ? params.citations.length : 0;
+        const nVer = Array.isArray(params?.verification) ? params.verification.length : 0;
+        return `EndTurn attestation (${nCit} citation(s), ${nVer} verification(s))`;
+    }
+    async execute(rawParams, _signal) {
+        const validationError = this.validateToolParams(rawParams);
+        if (validationError) {
+            return {
+                llmContent: `EndTurn rejected: ${validationError}. Fix the attestation and call EndTurn again.`,
+                success: false,
+                error: validationError,
+            };
+        }
+        // Normalize: absent arrays → [], malformed items dropped, missing strings → ''.
+        const params = this.normalizeParams(rawParams);
+        const cites = params.citations.length > 0
+            ? params.citations
+                .map((c) => ` - "${c.reference}" ⇐ ${c.verbatim_source}`)
+                .join('\n')
+            : ' (none cited)';
+        const vers = params.verification.length > 0
+            ? params.verification
+                .map((v) => ` - \`${v.command}\` ⇒ ${v.observed_result}`)
+                .join('\n')
+            : ' (none)';
+        const open = params.open_items.length > 0
+            ? params.open_items.map((o) => ` - ${o}`).join('\n')
+            : ' (none)';
+        // Echo the model's OWN reconstruction + skeptical review back at it. The
+        // model must now read its own self_review and act on it before
+        // finalizing — the reflection loop closes in its own context (no
+        // server-side verification in Stage 1).
+        const llmContent = `Attestation recorded — read your own review before finalizing:\n\n` +
+            `CITATIONS (each must be grounded in the verbatim source you gave):\n${cites}\n\n` +
+            `VERIFICATION:\n${vers}\n\n` +
+            `OPEN ITEMS:\n${open}\n\n` +
+            `YOUR SELF-REVIEW:\n  ${params.self_review}\n\n` +
+            `SUMMARY: ${params.summary}\n\n` +
+            `Now act on your own self-review: if it identified anything missed, wrong, or unverified, FIX it before answering — re-read or re-run as needed. ` +
+            `Your final answer MUST NOT contain any reference not backed by a verbatim_source above; if you can't ground it, quote the code/source instead of asserting a coordinate. ` +
+            `Then produce your final answer (the user-facing response) as plain text. Do not call any more tools.`;
+        return {
+            llmContent,
+            returnDisplay: `EndTurn: ${params.citations.length} cited, ${params.verification.length} verified`,
+            success: true,
+        };
+    }
+}
+//# sourceMappingURL=EndTurnTool.js.map

package/dist/implementations/extensions/EndTurnTool.js.map

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

package/dist/implementations/extensions/ResearchBacklogTool.d.ts

@@ -0,0 +1,37 @@
+/**
+ * ResearchBacklog tool — agent-facing interface to the recursive auto-research
+ * deficiency lifecycle (core `ResearchBacklog`). During benchmarking, the harness
+ * AUTO-ADDS every deficiency it finds, triages it (priority computed on add), and
+ * walks it through open → triaged → in_progress → fixed → verified → closed.
+ *
+ * OVERFITTING GUARD: `fixed` (passes the discovery task) is NOT `verified`
+ * (also holds on held-out tasks). Only call `verified` after held-out confirmation.
+ */
+import { BaseTool, type ToolResult } from '../../base/index.js';
+import { type Severity } from '@nexus-cortex/core';
+export interface ResearchBacklogParams {
+    action: 'add' | 'triage' | 'list' | 'next' | 'in_progress' | 'fixed' | 'verified' | 'close' | 'wont_fix' | 'regressed';
+    title?: string;
+    description?: string;
+    bugClass?: string;
+    severity?: Severity;
+    impact?: number;
+    effort?: number;
+    confidence?: number;
+    discoveredRound?: string;
+    affectedModels?: string[];
+    id?: string;
+    experimentTag?: string;
+    ref?: string;
+    status?: string;
+}
+export declare class ResearchBacklogToolExecutor extends BaseTool<ResearchBacklogParams, ToolResult> {
+    private backlog;
+    constructor(config: {
+        workingDirectory: string;
+    });
+    validateToolParams(p: ResearchBacklogParams): string | null;
+    execute(params: ResearchBacklogParams): Promise<ToolResult>;
+    private resultOr;
+}
+//# sourceMappingURL=ResearchBacklogTool.d.ts.map

package/dist/implementations/extensions/ResearchBacklogTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResearchBacklogTool.d.ts","sourceRoot":"","sources":["../../../src/implementations/extensions/ResearchBacklogTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEpE,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,WAAW,CAAC;IAEvH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,2BAA4B,SAAQ,QAAQ,CAAC,qBAAqB,EAAE,UAAU,CAAC;IAC1F,OAAO,CAAC,OAAO,CAAkB;gBAErB,MAAM,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAA;KAAE;IA4BhD,kBAAkB,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,GAAG,IAAI;IASrD,OAAO,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC;IA4CjE,OAAO,CAAC,QAAQ;CAKjB"}

package/dist/implementations/extensions/ResearchBacklogTool.js

@@ -0,0 +1,102 @@
+/**
+ * ResearchBacklog tool — agent-facing interface to the recursive auto-research
+ * deficiency lifecycle (core `ResearchBacklog`). During benchmarking, the harness
+ * AUTO-ADDS every deficiency it finds, triages it (priority computed on add), and
+ * walks it through open → triaged → in_progress → fixed → verified → closed.
+ *
+ * OVERFITTING GUARD: `fixed` (passes the discovery task) is NOT `verified`
+ * (also holds on held-out tasks). Only call `verified` after held-out confirmation.
+ */
+import { BaseTool } from '../../base/index.js';
+import { ResearchBacklog } from '@nexus-cortex/core';
+export class ResearchBacklogToolExecutor extends BaseTool {
+    backlog;
+    constructor(config) {
+        super('ResearchBacklog', 'ResearchBacklog', 'Track & triage harness deficiencies for recursive auto-research', {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['add', 'triage', 'list', 'next', 'in_progress', 'fixed', 'verified', 'close', 'wont_fix', 'regressed'],
+                    description: "add (auto-triages on add) | triage | list | next (highest-priority open item) | in_progress | fixed (passes discovery task) | verified (held-out confirmed — overfitting-cleared) | close | wont_fix | regressed",
+                },
+                title: { type: 'string', description: 'add: short deficiency title (also the dedupe key)' },
+                description: { type: 'string', description: 'add: what is wrong + how it was found' },
+                bugClass: { type: 'string', description: 'Adapter | Streaming | Caching | Loop control | Routing | Config | Model card | State | Infrastructure | TUI | Other' },
+                severity: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
+                impact: { type: 'number', description: '1-5: how much it degrades the harness' },
+                effort: { type: 'number', description: '1-5: estimated fix cost' },
+                confidence: { type: 'number', description: '0-1: how sure it is a real deficiency (not model noise)' },
+                discoveredRound: { type: 'string' },
+                affectedModels: { type: 'array', items: { type: 'string' } },
+                id: { type: 'string', description: 'target deficiency id (for triage/lifecycle ops)' },
+                experimentTag: { type: 'string', description: 'in_progress: the worktree experiment tag' },
+                ref: { type: 'string', description: 'fixed: commit SHA · verified: held-out round · wont_fix: reason' },
+                status: { type: 'string', description: 'list: filter by status' },
+            },
+            required: ['action'],
+        });
+        this.backlog = new ResearchBacklog(config.workingDirectory || process.env.PROJECT_ROOT || process.cwd());
+    }
+    validateToolParams(p) {
+        if (!p.action)
+            return 'action is required';
+        if (p.action === 'add' && (!p.title || !p.description))
+            return 'add requires title and description';
+        if (['triage', 'in_progress', 'fixed', 'verified', 'close', 'wont_fix', 'regressed'].includes(p.action) && !p.id) {
+            return `${p.action} requires an id (use action:list to find it)`;
+        }
+        return null;
+    }
+    async execute(params) {
+        const err = this.validateToolParams(params);
+        if (err)
+            return this.createErrorResult(err);
+        try {
+            const fmt = (r) => JSON.stringify(r, null, 2);
+            switch (params.action) {
+                case 'add':
+                    return this.createSuccessResult(fmt(this.backlog.add({
+                        title: params.title, description: params.description, bugClass: params.bugClass,
+                        severity: params.severity, impact: params.impact, effort: params.effort, confidence: params.confidence,
+                        discoveredRound: params.discoveredRound, affectedModels: params.affectedModels,
+                    })));
+                case 'triage':
+                    return this.resultOr(this.backlog.triage(params.id, {
+                        severity: params.severity, impact: params.impact, effort: params.effort, confidence: params.confidence,
+                    }), params.id);
+                case 'list': {
+                    const items = this.backlog.list({ status: params.status });
+                    return this.createSuccessResult(`${items.length} deficiencies (by priority):\n${fmt(items)}`);
+                }
+                case 'next': {
+                    const n = this.backlog.next();
+                    return this.createSuccessResult(n ? fmt(n) : 'No open/triaged deficiencies in the backlog.');
+                }
+                case 'in_progress':
+                    return this.resultOr(this.backlog.markInProgress(params.id, params.experimentTag ?? 'untagged'), params.id);
+                case 'fixed':
+                    return this.resultOr(this.backlog.markFixed(params.id, params.ref ?? ''), params.id);
+                case 'verified':
+                    return this.resultOr(this.backlog.markVerified(params.id, params.ref ?? ''), params.id);
+                case 'close':
+                    return this.resultOr(this.backlog.close(params.id), params.id);
+                case 'wont_fix':
+                    return this.resultOr(this.backlog.wontFix(params.id, params.ref ?? 'no reason given'), params.id);
+                case 'regressed':
+                    return this.resultOr(this.backlog.reopenRegressed(params.id), params.id);
+                default:
+                    return this.createErrorResult(`Unknown action: ${params.action}`);
+            }
+        }
+        catch (e) {
+            return this.createErrorResult(e instanceof Error ? e : String(e));
+        }
+    }
+    resultOr(rec, id) {
+        return rec
+            ? this.createSuccessResult(JSON.stringify(rec, null, 2))
+            : this.createErrorResult(`No deficiency with id "${id}" (use action:list).`);
+    }
+}
+//# sourceMappingURL=ResearchBacklogTool.js.map

package/dist/implementations/extensions/ResearchBacklogTool.js.map

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

package/dist/implementations/extensions/SkillTool.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Skill Tool - Invoke specialized skills from .agents/skills/ or .cortex/skills/
+ *
+ * Loads and invokes skills defined as directories containing SKILL.md files
+ * with YAML frontmatter. Skills are model-invoked capabilities that extend
+ * the agent's functionality.
+ *
+ * Search order: .agents/skills/ → .cortex/skills/ → ~/.cortex/skills/
+ */
+import { BaseTool, type ToolResult } from '../../base/index.js';
+/**
+ * Parameters for the Skill tool
+ */
+export interface SkillParams {
+    /** The skill name (no arguments), e.g., "pdf" or "xlsx" */
+    command: string;
+}
+/**
+ * Skill Tool Executor
+ *
+ * Invokes specialized skills from skill directories.
+ * Skills are model-invoked capabilities defined in SKILL.md files.
+ *
+ * Example skill directory structure:
+ * ```
+ * .agents/skills/pdf-documents/
+ * ├── SKILL.md          # Required: skill definition
+ * ├── sections/         # Optional: spoke files referenced by hub
+ * ├── reference.md      # Optional: reference docs
+ * └── scripts/          # Optional: helper scripts
+ * ```
+ *
+ * Search order (first match wins — cwd-specific overrides/extends central):
+ * 1. Project `.agents/skills/` (cwd-specific overlay — cross-harness convention)
+ * 2. Project `.cortex/skills/` (cwd-specific overlay — nexus-cortex native)
+ * 3. Central `~/.agents/skills/` (the universal master list, shared across cwds)
+ * 4. Personal `~/.cortex/skills/` (nexus-cortex personal skills)
+ *
+ * Skills are mostly universal, so they live centrally in `~/.agents/skills/`
+ * and are reachable from any cwd; a project may add cwd-specific skills (or
+ * override a central one) by name in its own `.agents/skills/`, searched first.
+ *
+ * Usage: Skill({ command: "pdf-documents" })
+ */
+export declare class SkillToolExecutor extends BaseTool<SkillParams, ToolResult> {
+    private skillsCache;
+    private skillsDirs;
+    constructor(config: {
+        workingDirectory: string;
+    });
+    validateToolParams(params: SkillParams): string | null;
+    getDescription(params: SkillParams): string;
+    execute(params: SkillParams, signal: AbortSignal, updateOutput?: (output: string) => void): Promise<ToolResult>;
+    /**
+     * Load skill definition from .cortex/skills/ directories
+     * Searches project skills first, then personal skills
+     */
+    private loadSkill;
+    /**
+     * Load all skill definitions from project and personal directories.
+     * First match wins — earlier dirs in skillsDirs take precedence.
+     */
+    private loadAllSkills;
+    /**
+     * Load skills from a specific directory
+     */
+    private loadSkillsFromDirectory;
+    /**
+     * Parse skill definition from SKILL.md file
+     *
+     * Format:
+     * ```markdown
+     * ---
+     * name: skill-name
+     * description: What this skill does
+     * allowed-tools: Read, Write, Grep  # Optional
+     * ---
+     *
+     * # Skill Name
+     *
+     * ## Instructions
+     * Step-by-step guidance...
+     * ```
+     */
+    private parseSkillFile;
+    /**
+     * Simple YAML frontmatter parser
+     * Handles basic key: value pairs
+     */
+    private parseFrontmatter;
+    /**
+     * Format skill output for display
+     */
+    private formatSkillOutput;
+    /**
+     * Format a readable listing of all available skills
+     */
+    private formatSkillListing;
+    /**
+     * Get list of available skills (for error messages)
+     */
+    private getAvailableSkills;
+    /**
+     * Clear the skills cache (useful for testing or reloading)
+     */
+    clearCache(): void;
+}
+//# sourceMappingURL=SkillTool.d.ts.map

package/dist/implementations/extensions/SkillTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SkillTool.d.ts","sourceRoot":"","sources":["../../../src/implementations/extensions/SkillTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAMhE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;CACjB;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACtE,OAAO,CAAC,WAAW,CAA6C;IAChE,OAAO,CAAC,UAAU,CAA+E;gBAErF,MAAM,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAA;KAAE;IA6BhD,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI;IAmBtD,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM;IAKrC,OAAO,CACX,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,WAAW,EACnB,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GACtC,OAAO,CAAC,UAAU,CAAC;IA6EtB;;;OAGG;YACW,SAAS;IAgBvB;;;OAGG;YACW,aAAa;IAQ3B;;OAEG;YACW,uBAAuB;IA4CrC;;;;;;;;;;;;;;;;OAgBG;YACW,cAAc;IAkD5B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAgBxB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAuBzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;OAEG;YACW,kBAAkB;IAchC;;OAEG;IACH,UAAU,IAAI,IAAI;CAGnB"}