icoa-cli 2.2.3 → 2.3.1

package/dist/commands/ai4ctf.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerAi4ctfCommand(program: Command): void;

package/dist/commands/ai4ctf.js

@@ -0,0 +1,110 @@
+import { createInterface } from 'node:readline';
+import chalk from 'chalk';
+import { createChatSession } from '../lib/gemini.js';
+import { isTokenCapReached, addTokenUsage, getTokenUsage } from '../lib/budget.js';
+import { getConfig } from '../lib/config.js';
+import { logCommand } from '../lib/logger.js';
+import { printMarkdown, printError, printInfo } from '../lib/ui.js';
+function getChallengeContext() {
+    const config = getConfig();
+    if (config.currentChallengeName && config.currentChallengeCategory) {
+        return { name: config.currentChallengeName, category: config.currentChallengeCategory };
+    }
+    return undefined;
+}
+export function registerAi4ctfCommand(program) {
+    program
+        .command('ai4ctf')
+        .description('Chat with your AI teammate')
+        .action(async () => {
+        logCommand('ai4ctf');
+        // Check token cap
+        if (isTokenCapReached()) {
+            printError('Token budget exhausted. No more AI interactions available.');
+            return;
+        }
+        const context = getChallengeContext();
+        const tokenState = getTokenUsage();
+        // Create chat session
+        let chat;
+        try {
+            chat = await createChatSession(context);
+        }
+        catch (err) {
+            printError(err.message);
+            return;
+        }
+        // Welcome banner
+        console.log();
+        console.log(chalk.magenta('  ┌─────────────────────────────────────────┐'));
+        console.log(chalk.magenta('  │') + chalk.bold.white('  AI Teammate — Chat Mode') + chalk.magenta('                │'));
+        if (context) {
+            const ctxStr = `  Challenge: ${context.name} (${context.category})`;
+            console.log(chalk.magenta('  │') + chalk.gray(ctxStr.padEnd(41)) + chalk.magenta('│'));
+        }
+        const tokenStr = `  Tokens: ${tokenState.used.toLocaleString()}/${tokenState.cap.toLocaleString()}`;
+        console.log(chalk.magenta('  │') + chalk.gray(tokenStr.padEnd(41)) + chalk.magenta('│'));
+        console.log(chalk.magenta('  │') + chalk.gray("  Type 'exit' to return".padEnd(41)) + chalk.magenta('│'));
+        console.log(chalk.magenta('  └─────────────────────────────────────────┘'));
+        console.log();
+        // Inner chat REPL
+        return new Promise((resolve) => {
+            const chatRl = createInterface({
+                input: process.stdin,
+                output: process.stdout,
+                prompt: chalk.magenta('ai> '),
+                terminal: true,
+            });
+            chatRl.prompt();
+            chatRl.on('line', async (line) => {
+                const input = line.trim();
+                if (!input) {
+                    chatRl.prompt();
+                    return;
+                }
+                // Exit commands
+                if (input === 'exit' || input === 'back' || input === 'quit') {
+                    chatRl.close();
+                    return;
+                }
+                // Token cap check
+                if (isTokenCapReached()) {
+                    console.log();
+                    printError('Token budget exhausted. Exiting chat mode.');
+                    chatRl.close();
+                    return;
+                }
+                // Log the chat message
+                logCommand(`ai4ctf: ${input}`);
+                // Send message
+                console.log(chalk.gray('  Thinking...'));
+                try {
+                    const response = await chat.sendMessage(input);
+                    // Clear "Thinking..." line
+                    process.stdout.write('\x1b[1A\x1b[2K');
+                    // Track tokens
+                    addTokenUsage(response.tokensUsed);
+                    const updated = getTokenUsage();
+                    // Display response
+                    console.log();
+                    printMarkdown(response.text);
+                    console.log(chalk.gray(`  [${response.tokensUsed.toLocaleString()} tokens | ${updated.used.toLocaleString()}/${updated.cap.toLocaleString()} total]`));
+                    console.log();
+                }
+                catch (err) {
+                    // Clear "Thinking..." line
+                    process.stdout.write('\x1b[1A\x1b[2K');
+                    printError(`AI error: ${err.message}`);
+                    console.log();
+                }
+                chatRl.prompt();
+            });
+            chatRl.on('close', () => {
+                console.log();
+                printInfo('Returning to ICOA terminal.');
+                console.log();
+                resolve();
+            });
+        });
+    });
+}

package/dist/index.js

@@ -12,6 +12,7 @@ import { registerLogCommand } from './commands/log.js';
 import { registerLangCommand } from './commands/lang.js';
 import { registerSetupCommand } from './commands/setup.js';
 import { registerEnvCommand } from './commands/env.js';
+import { registerAi4ctfCommand } from './commands/ai4ctf.js';
 import { getConfig, saveConfig } from './lib/config.js';
 import { startRepl } from './repl.js';
 import { setTerminalTheme } from './lib/theme.js';
@@ -36,7 +37,7 @@ ${LINE}
    ${chalk.white('Sydney, Australia')}  ${chalk.gray('Jun 27 - Jul 2, 2026')}
    ${chalk.cyan.underline('https://icoa2026.au')}
 
-   ${chalk.gray('CLI-Native Competition Terminal  v2.2.3')}
+   ${chalk.gray('CLI-Native Competition Terminal  v2.3.1')}
 
 ${LINE}
 `;
@@ -81,6 +82,7 @@ registerLogCommand(program);
 registerLangCommand(program);
 registerSetupCommand(program);
 registerEnvCommand(program);
+registerAi4ctfCommand(program);
 // Hidden command: switch AI model
 program
     .command('model', { hidden: true })

package/dist/lib/budget.d.ts

@@ -6,3 +6,9 @@ export declare function checkBudget(level: HintLevel): {
 export declare function deductBudget(level: HintLevel, tokensUsed: number): void;
 export declare function getBudgetDisplay(): string;
 export declare function isTokenCapReached(): boolean;
+export declare function addTokenUsage(tokensUsed: number): void;
+export declare function getTokenUsage(): {
+    used: number;
+    cap: number;
+    remaining: number;
+};

package/dist/lib/budget.js

@@ -27,3 +27,16 @@ export function isTokenCapReached() {
     const budget = getBudget();
     return budget.tokensUsed >= budget.tokenCap;
 }
+export function addTokenUsage(tokensUsed) {
+    const budget = getBudget();
+    budget.tokensUsed += tokensUsed;
+    saveBudget(budget);
+}
+export function getTokenUsage() {
+    const budget = getBudget();
+    return {
+        used: budget.tokensUsed,
+        cap: budget.tokenCap,
+        remaining: Math.max(0, budget.tokenCap - budget.tokensUsed),
+    };
+}

package/dist/lib/gemini.d.ts

@@ -1,7 +1,14 @@
 import type { HintLevel, ChallengeContext } from '../types/index.js';
+export declare function filterFlagPatterns(text: string): string;
 export declare function generateHint(level: HintLevel, question: string, context?: ChallengeContext): Promise<{
     text: string;
     tokensUsed: number;
 }>;
 export declare function translateText(text: string, targetLang: string): Promise<string>;
 export declare function setApiKey(key: string): void;
+export declare function createChatSession(context?: ChallengeContext): Promise<{
+    sendMessage: (msg: string) => Promise<{
+        text: string;
+        tokensUsed: number;
+    }>;
+}>;

package/dist/lib/gemini.js

@@ -37,9 +37,11 @@ function buildSystemPrompt(level, context) {
     }
     return prompt;
 }
-function filterFlagPatterns(text) {
+export function filterFlagPatterns(text) {
     return text.replace(/icoa\{[^}]*\}/gi, '[FLAG REDACTED]');
 }
+// Default shared API key for competition (free tier)
+const DEFAULT_API_KEY = 'AIzaSyB7XgD1n1S5sCtSabkaXKSVk3L2D9es6As';
 function getApiKey() {
     const envKey = process.env.GEMINI_API_KEY;
     if (envKey)
@@ -47,7 +49,7 @@ function getApiKey() {
     const config = getConfig();
     if (config.geminiApiKey)
         return config.geminiApiKey;
-    return '';
+    return DEFAULT_API_KEY;
 }
 function getClient(apiKey) {
     return new GoogleGenAI({ apiKey });
@@ -112,3 +114,62 @@ ${text}`;
 export function setApiKey(key) {
     saveConfig({ geminiApiKey: key });
 }
+const CHAT_SYSTEM_PROMPT = `You are an AI teammate in the ICOA cybersecurity CTF competition (International Cyber Olympiad in AI 2026, Sydney).
+
+You're a friendly, knowledgeable hacking partner — like a fellow competitor sitting next to the user. Be conversational, encouraging, and collaborative.
+
+RULES:
+- Help the competitor think through challenges, brainstorm approaches, explain concepts
+- You MAY discuss vulnerability types, tools, techniques, and methodologies
+- You MAY suggest approaches and help debug code
+- Do NOT provide complete working exploits or full solution scripts
+- Do NOT provide flags or flag fragments
+- Never output anything matching flag format: icoa{...}
+- If you don't know something, say so honestly
+- Keep responses concise unless the user asks for detail
+- When the user opens a challenge, use the context to give relevant advice`;
+export async function createChatSession(context) {
+    let apiKey = getApiKey();
+    if (!apiKey) {
+        try {
+            const { input } = await import('@inquirer/prompts');
+            console.log();
+            console.log('  Gemini API key not configured.');
+            console.log('  Get one free at: https://aistudio.google.com/apikey');
+            console.log();
+            apiKey = await input({ message: 'Enter your Gemini API Key:' });
+            if (apiKey.trim()) {
+                apiKey = apiKey.trim();
+                saveConfig({ geminiApiKey: apiKey });
+                console.log('  Key saved for future use.');
+                console.log();
+            }
+            else {
+                throw new Error('No API key provided.');
+            }
+        }
+        catch {
+            throw new Error('Gemini API key not configured. Run: setup');
+        }
+    }
+    const config = getConfig();
+    const modelName = config.geminiModel || 'gemini-2.5-flash';
+    const ai = getClient(apiKey);
+    let systemPrompt = CHAT_SYSTEM_PROMPT;
+    if (context) {
+        systemPrompt += `\n\nThe competitor is currently working on:\nChallenge: ${context.name}\nCategory: ${context.category}`;
+    }
+    const chat = ai.chats.create({
+        model: modelName,
+        config: { systemInstruction: systemPrompt },
+    });
+    return {
+        async sendMessage(msg) {
+            const response = await chat.sendMessage({ message: msg });
+            const text = filterFlagPatterns(response.text ?? '');
+            const usage = response.usageMetadata;
+            const tokensUsed = usage?.totalTokenCount || ((usage?.promptTokenCount || 0) + (usage?.candidatesTokenCount || 0));
+            return { text, tokensUsed };
+        },
+    };
+}

package/dist/repl.js

@@ -27,7 +27,7 @@ const BLOCKED_COMMANDS = new Set([
     'iptables', 'ufw', // firewall
 ]);
 const INTERCEPT = '__REPL_NO_EXIT__';
-const VERSION = '2.2.3';
+const VERSION = '2.3.1';
 export async function startRepl(program, resumeMode) {
     const config = getConfig();
     const connected = isConnected();
@@ -212,7 +212,7 @@ export async function startRepl(program, resumeMode) {
             'join', 'activate', 'challenges', 'ch', 'open', 'submit', 'flag',
             'scoreboard', 'sb', 'status', 'time', 'hint', 'hint-b', 'hint-c',
             'hint-budget', 'ref', 'shell', 'files', 'connect', 'note',
-            'log', 'lang', 'setup', 'env', 'model', 'ctf',
+            'log', 'lang', 'setup', 'env', 'ai4ctf', 'model', 'ctf',
         ];
         if (!knownCommands.includes(cmd)) {
             // Block dangerous commands
@@ -287,6 +287,8 @@ export async function startRepl(program, resumeMode) {
         process.exit = (() => {
             throw new Error(INTERCEPT);
         });
+        // Pause main readline so sub-REPLs (ai4ctf) can use stdin
+        rl.pause();
         try {
             await program.parseAsync(['node', 'icoa', ...args]);
         }
@@ -308,6 +310,7 @@ export async function startRepl(program, resumeMode) {
         finally {
             process.exit = realExit;
             processing = false;
+            rl.resume();
         }
         console.log();
         rl.prompt();
@@ -360,7 +363,7 @@ function mapCommand(input) {
     const directCommands = [
         'hint', 'hint-b', 'hint-c', 'hint-budget',
         'ref', 'shell', 'files', 'connect', 'note',
-        'log', 'lang', 'setup', 'model',
+        'log', 'lang', 'setup', 'env', 'ai4ctf', 'model',
         'ctf',
     ];
     if (directCommands.includes(cmd)) {
@@ -388,7 +391,8 @@ function printReplHelp(activated) {
     console.log(chalk.white('    status              ') + chalk.gray('Competition status'));
     console.log(chalk.white('    time                ') + chalk.gray('Countdown timer'));
     console.log();
-    console.log(chalk.bold.white('  AI Hints'));
+    console.log(chalk.bold.white('  AI'));
+    console.log(chalk.white('    ai4ctf              ') + chalk.gray('Chat with your AI teammate'));
     console.log(chalk.white('    hint <question>     ') + chalk.gray('Level A — General guidance'));
     console.log(chalk.white('    hint-b <question>   ') + chalk.gray('Level B — Deep analysis'));
     console.log(chalk.white('    hint-c <question>   ') + chalk.gray('Level C — Critical assist'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icoa-cli",
-  "version": "2.2.3",
+  "version": "2.3.1",
   "description": "ICOA CLI — The world's first CLI-native CTF competition terminal",
   "type": "module",
   "bin": {