icoa-cli 2.19.348 → 2.19.349

package/dist/lib/gemini.js

@@ -1 +1,247 @@
-import{GoogleGenAI as e}from"@google/genai";import chalk from"chalk";import{readFileSync as t}from"node:fs";import{dirname as n,join as o}from"node:path";import{fileURLToPath as a}from"node:url";import{getConfig as r,saveConfig as s}from"./config.js";import{getRealExamState as i}from"./exam-state.js";const c=n(a(import.meta.url));let l=null;function u(){if(l)return l;try{const e=JSON.parse(t(o(c,"..","..","package.json"),"utf-8"));l=e.version||"unknown"}catch{l="unknown"}return l}export async function translateText(e,t){throw new Error("Local AI model path has been disabled (2026-04-24). ICOA provides all AI server-side — no API key setup needed. Use `ai4ctf` (chat) or `exam` (with integrated help/hint) instead.")}export function setApiKey(e){s({geminiApiKey:e})}export async function createChatSession(e,t){const n=r();let o=t||"You are an AI teammate in the ICOA cybersecurity CTF competition (International Cyber Olympiad in AI 2026, Sydney).\n\nYou're a friendly, knowledgeable cybersecurity partner — like a fellow competitor sitting next to the user. Be conversational, encouraging, and collaborative.\n\nRULES:\n- Help the competitor think through challenges, brainstorm approaches, explain concepts\n- You MAY discuss vulnerability types, tools, techniques, and methodologies\n- You MAY suggest approaches and help debug code\n- Do NOT provide complete working exploits or full solution scripts\n- Do NOT provide flags or flag fragments\n- Never output anything matching flag format: icoa{...}\n- If you don't know something, say so honestly\n- Keep responses concise unless the user asks for detail\n- When the user opens a challenge, use the context to give relevant advice";e&&(o+=`\n\nThe competitor is currently working on:\nChallenge: ${e.name}\nCategory: ${e.category}`),o+='\n\nINTEGRITY — give method, not the produced answer:\n- You may name the tool/command/technique (e.g. "this is base64; run base64 -d on the file").\n- Do NOT perform a solution step for the competitor and hand back its result: never decode,\n  decrypt, deobfuscate, run, execute, or compute over data they paste or that is attached,\n  and then reveal the produced value. They must run it themselves and read the output.\n- Do NOT reveal the exact final answer, and never output icoa{...} / flag{...} in any case.\n- If asked to "just give the answer" / "solve it" / "decode this and tell me", refuse and\n  nudge them to do the step themselves.';const a=n.ctfdUrl||"https://practice.icoa2026.au",s=n.deviceFingerprint||"",c=n.geminiModel||"gemini-2.5-flash-lite",l=[];return{async sendMessage(e){l.push({role:"user",text:e});const t=i(),r={systemPrompt:o,messages:l,model:c,maxTokens:2048,deviceFingerprint:s};t?.session?.token&&(r.examToken=t.session.token);const p={"Content-Type":"application/json","User-Agent":`icoa-cli/${u()}`,"X-Device-Fingerprint":s};!r.examToken&&n.ctfdUrl&&n.token&&n.userName&&(r.account=n.userName,p.Authorization=`Token ${n.token}`);const d=e=>new Promise(t=>setTimeout(t,e)),h=[2e3,5e3];let m=null,g=null;for(let e=0;e<=h.length&&(m=await fetch(`${a}/api/icoa/ai/chat`,{method:"POST",headers:p,body:JSON.stringify(r),signal:AbortSignal.timeout(6e4)}),!m.ok&&429===m.status);e++)e<h.length?await d(h[e]):g=m;if(!m)throw new Error("AI proxy: no response");if(!m.ok){const e=(await m.json().catch(()=>({message:"AI proxy error"}))).message||`AI proxy returned ${m.status}`;if(401===m.status)throw new Error(`${chalk.yellow("⚠ ")}Exam token expired. Re-enter via \`exam <token>\`.`);if(403===m.status)throw new Error(chalk.yellow("⚠ ")+e);if(429===m.status)throw new Error(chalk.yellow("⏳ ")+e+chalk.gray(" (retried twice — quota burst, try again in ~30s)"));throw new Error(e)}const f=await m.json(),y=function(e){return e.replace(/icoa\{[^}]*\}/gi,"[FLAG REDACTED]")}(f.data?.text||""),w=f.data?.tokensUsed||0,v="number"==typeof f.data?.accountSpent?f.data.accountSpent:void 0,k="number"==typeof f.data?.accountCap?f.data.accountCap:void 0;return l.push({role:"model",text:y}),{text:y,tokensUsed:w,accountSpent:v,accountCap:k}}}}
+import { GoogleGenAI } from '@google/genai';
+import chalk from 'chalk';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getConfig, saveConfig } from './config.js';
+import { getRealExamState } from './exam-state.js';
+const __dirname_gemini = dirname(fileURLToPath(import.meta.url));
+let _cachedVersion = null;
+function getCliVersion() {
+    if (_cachedVersion)
+        return _cachedVersion;
+    try {
+        const pkg = JSON.parse(readFileSync(join(__dirname_gemini, '..', '..', 'package.json'), 'utf-8'));
+        _cachedVersion = pkg.version || 'unknown';
+    }
+    catch {
+        _cachedVersion = 'unknown';
+    }
+    return _cachedVersion;
+}
+const SYSTEM_PROMPTS = {
+    A: `You are an AI assistant in a cybersecurity CTF competition called ICOA.
+You are providing Level A (General Guidance) to a competitor.
+
+STRICT RULES:
+- Only answer conceptual questions
+- Do NOT mention specific vulnerability names
+- Do NOT provide any code, commands, or tool usage
+- Do NOT mention specific attack techniques
+- Use questions to guide the competitor toward their own discovery
+- If the competitor asks you to solve the challenge, refuse and redirect
+- Never output anything matching flag format: icoa{...}`,
+    B: `You are an AI assistant in ICOA CTF, providing Level B (Deep Analysis).
+
+RULES:
+- You MAY identify specific vulnerability types (e.g., "buffer overflow")
+- You MAY suggest which category of tool to use (e.g., "a debugger")
+- Do NOT provide complete commands or working code
+- Do NOT provide exploit code or payloads
+- Do NOT provide flags or flag fragments
+- Never output anything matching: icoa{...}`,
+    C: `You are an AI assistant in ICOA CTF, providing Level C (Critical Assist).
+
+RULES:
+- You MAY provide the key conceptual breakthrough
+- You MAY name specific algorithms or approaches
+- Do NOT provide complete exploit code
+- Do NOT provide the flag
+- Never output anything matching: icoa{...}`,
+};
+function _buildSystemPrompt(level, context) {
+    let prompt = SYSTEM_PROMPTS[level];
+    if (context) {
+        prompt += `\n\nThe competitor is currently working on:\nChallenge: ${context.name}\nCategory: ${context.category}`;
+    }
+    prompt += METHOD_NOT_ANSWER_RULE;
+    return prompt;
+}
+function filterFlagPatterns(text) {
+    return text.replace(/icoa\{[^}]*\}/gi, '[FLAG REDACTED]');
+}
+// No DEFAULT_API_KEY in client code — keys stay server-side only.
+// 2026-04-24: **Local model path disabled**. All AI routes through the
+// server proxy at /api/icoa/ai/chat regardless of whether the user has
+// their own GEMINI_API_KEY. See reference_ai_models.md / feedback_icoa_all_keys.md.
+// ICOA centrally owns all AI keys; students do not need to configure anything.
+const LOCAL_MODEL_DISABLED_MESSAGE = 'Local AI model path has been disabled (2026-04-24). ' +
+    'ICOA provides all AI server-side — no API key setup needed. ' +
+    'Use `ai4ctf` (chat) or `exam` (with integrated help/hint) instead.';
+function getApiKey() {
+    // Returns empty string to disable Path A in createChatSession / generateHint.
+    // Preserved as a function to keep the call sites stable for future refactors.
+    return '';
+}
+function getClient(apiKey) {
+    return new GoogleGenAI({ apiKey });
+}
+/**
+ * @deprecated Runtime translation is disabled. Translations are pre-baked
+ * at build time via `panda/translate-*.js` scripts and shipped in
+ * `translations/<lang>/` — CLI never translates at runtime.
+ */
+export async function translateText(_text, _targetLang) {
+    throw new Error(LOCAL_MODEL_DISABLED_MESSAGE);
+}
+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 cybersecurity 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`;
+// Shared "method, not answer" rule appended to every system prompt. The
+// server (token-api.py) enforces the authoritative copy of these rules so a
+// modified/curl client can't strip them; this client copy keeps the stock CLI
+// well-behaved without a server round-trip. Phrased to allow naming the
+// command but forbid performing the step and returning its result.
+const METHOD_NOT_ANSWER_RULE = `
+
+INTEGRITY — give method, not the produced answer:
+- You may name the tool/command/technique (e.g. "this is base64; run base64 -d on the file").
+- Do NOT perform a solution step for the competitor and hand back its result: never decode,
+  decrypt, deobfuscate, run, execute, or compute over data they paste or that is attached,
+  and then reveal the produced value. They must run it themselves and read the output.
+- Do NOT reveal the exact final answer, and never output icoa{...} / flag{...} in any case.
+- If asked to "just give the answer" / "solve it" / "decode this and tell me", refuse and
+  nudge them to do the step themselves.`;
+export async function createChatSession(context, customSystemPrompt) {
+    const config = getConfig();
+    const apiKey = getApiKey();
+    let systemPrompt = customSystemPrompt || CHAT_SYSTEM_PROMPT;
+    if (context) {
+        systemPrompt += `\n\nThe competitor is currently working on:\nChallenge: ${context.name}\nCategory: ${context.category}`;
+    }
+    // Always append the integrity rule (covers chat + exam custom prompts).
+    systemPrompt += METHOD_NOT_ANSWER_RULE;
+    // ─── Path A: user has their own key → direct Gemini SDK ───
+    if (apiKey) {
+        const modelName = config.geminiModel || 'gemini-2.5-flash-lite';
+        const ai = getClient(apiKey);
+        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 };
+            },
+        };
+    }
+    // ─── Path B: no key → server proxy (key stays server-side) ───
+    const serverUrl = config.ctfdUrl || 'https://practice.icoa2026.au';
+    const fp = config.deviceFingerprint || '';
+    const modelName = config.geminiModel || 'gemini-2.5-flash-lite';
+    const messages = [];
+    return {
+        async sendMessage(msg) {
+            messages.push({ role: 'user', text: msg });
+            // Attach exam token if contestant is in a real exam — grants full
+            // 2048 maxTokens and higher rate limit. Demo/anonymous users rely on
+            // the User-Agent gate on the server side.
+            const realExam = getRealExamState();
+            const payload = {
+                systemPrompt,
+                messages,
+                model: modelName,
+                maxTokens: 2048,
+                deviceFingerprint: fp,
+            };
+            if (realExam?.session?.token) {
+                payload.examToken = realExam.session.token;
+            }
+            // CTFd-join account binding (2026-06-17, AU-camp audit). When connected
+            // to a CTFd event (no exam token), attribute AI usage to the logged-in
+            // account so the server can (a) audit per-student and (b) meter a
+            // per-account budget — a shared-NAT room can no longer pool unlimited
+            // AI. Ignored server-side when an exam token is present (exam-token
+            // budget wins); demo/practice has no CTFd login → no account → stays on
+            // the client 5k cap.
+            //
+            // 2026-06-20 (Olympic audit upgrade): also send the CTFd API token in an
+            // Authorization header so the server can VERIFY the account against CTFd's
+            // own tokens→users tables instead of trusting the self-reported username
+            // below. The header turns attribution from a forgeable signal into
+            // evidence (account_verified=1 server-side). payload.account stays as a
+            // fallback for any pre-upgrade server. Mirrors the /api/icoa/audit auth.
+            const reqHeaders = {
+                'Content-Type': 'application/json',
+                'User-Agent': `icoa-cli/${getCliVersion()}`,
+                'X-Device-Fingerprint': fp,
+            };
+            if (!payload.examToken && config.ctfdUrl && config.token && config.userName) {
+                payload.account = config.userName;
+                reqHeaders.Authorization = `Token ${config.token}`;
+            }
+            // V2.19.185: 429 retry-with-backoff. UZ Paper A (2026-05-17) had a
+            // sustained Gemini upstream quota burst that caused 45 client-visible
+            // 429s. Server-side key rotation eventually recovers, so a short
+            // backoff before retrying transparently absorbs most transient dips
+            // without the contestant ever seeing an error. We retry up to twice
+            // with 2s and 5s backoff (max ~7s added latency on a worst-case path).
+            // 401/403 are surfaced immediately — they need contestant action.
+            const sleepMs = (ms) => new Promise((r) => setTimeout(r, ms));
+            const BACKOFFS_MS = [2000, 5000];
+            let res = null;
+            let lastErr = null;
+            for (let attempt = 0; attempt <= BACKOFFS_MS.length; attempt++) {
+                res = await fetch(`${serverUrl}/api/icoa/ai/chat`, {
+                    method: 'POST',
+                    headers: reqHeaders,
+                    body: JSON.stringify(payload),
+                    signal: AbortSignal.timeout(60_000),
+                });
+                if (res.ok || res.status !== 429)
+                    break;
+                // 429 — try again after backoff if we have budget left
+                if (attempt < BACKOFFS_MS.length) {
+                    await sleepMs(BACKOFFS_MS[attempt]);
+                    continue;
+                }
+                // Out of retries — fall through to error handling below
+                lastErr = res;
+            }
+            if (!res)
+                throw new Error('AI proxy: no response');
+            if (!res.ok) {
+                const err = (await res.json().catch(() => ({ message: 'AI proxy error' })));
+                const msg = err.message || `AI proxy returned ${res.status}`;
+                if (res.status === 401) {
+                    throw new Error(`${chalk.yellow('⚠ ')}Exam token expired. Re-enter via \`exam <token>\`.`);
+                }
+                if (res.status === 403) {
+                    throw new Error(chalk.yellow('⚠ ') + msg);
+                }
+                if (res.status === 429) {
+                    throw new Error(chalk.yellow('⏳ ') + msg + chalk.gray(' (retried twice — quota burst, try again in ~30s)'));
+                }
+                throw new Error(msg);
+            }
+            const json = (await res.json());
+            const text = filterFlagPatterns(json.data?.text || '');
+            const tokensUsed = json.data?.tokensUsed || 0;
+            // Server-authoritative cumulative per-account spend (CTFd-join comp mode).
+            // Present only when the server metered a verified account; the client uses
+            // it to render a TRUE budget bar instead of a per-session counter.
+            const accountSpent = typeof json.data?.accountSpent === 'number' ? json.data.accountSpent : undefined;
+            const accountCap = typeof json.data?.accountCap === 'number' ? json.data.accountCap : undefined;
+            messages.push({ role: 'model', text });
+            return { text, tokensUsed, accountSpent, accountCap };
+        },
+    };
+}

package/dist/lib/integrity-snapshot.js

@@ -1 +1,88 @@
-import{readFileSync as t}from"node:fs";import{join as n}from"node:path";import{homedir as o}from"node:os";import{getConfig as e,getBudget as i}from"./config.js";import{getCliVersion as r}from"./version.js";function s(n){try{return JSON.parse(t(n,"utf-8"))}catch{return null}}export async function postIntegritySnapshot(){try{const t=e();if("live"!==t.competitionState)return;const a=t.ctfdUrl;if(!a)return;const c=n(o(),".icoa"),p=i(),d={deviceFingerprint:t.deviceFingerprint||"",installSalt:t.installSalt||"",budget:{tokensUsed:p.tokensUsed,tokenCap:p.tokenCap},simCooldown:s(n(c,"sim-cooldown.json")),tokenBindings:s(n(c,"token-bindings.json"))},m={"Content-Type":"application/json","User-Agent":`icoa-cli/${r()}`,"X-Device-Fingerprint":t.deviceFingerprint||""};t.token&&t.userName&&(d.account=t.userName,m.Authorization=`Token ${t.token}`),await fetch(`${a}/api/icoa/snapshot`,{method:"POST",headers:m,body:JSON.stringify(d),signal:AbortSignal.timeout(8e3)})}catch{}}
+// Submit-triggered integrity sampling (P1.5 — detective layer).
+//
+// On the flag-submit path we fire a SECOND, fire-and-forget POST to our own
+// server carrying a SCRUBBED snapshot of client-only-knowable state, anchored
+// to a real server-recorded scoring event (the CTFd submission). The server
+// debounces (first per 5-min window, server-side so a cheater can't suppress
+// it), reconciles against its own authoritative ledger, and stores the row in
+// an auditable SQLite table.
+//
+// This is DETECTIVE-ONLY: it never auto-judges, never blocks a submit, and
+// never reveals any verdict to the client. It catches casual tampering
+// (`echo > budget.json`, `rm sim-cooldown.json`) and cross-account fingerprint
+// reuse. A sophisticated forger who also fakes consistent snapshots evades it —
+// it COMPLEMENTS the server-authoritative scoring surfaces (§9 of
+// docs/POST_COMPETITION_AUDIT_STANDARD.md), it does not replace them.
+//
+// HARD RULES honored here (see §11):
+//   - Gate on competitionState === 'live' (sample only during the contest).
+//   - NEVER upload secrets: config.accessToken / config.token are excluded.
+//   - Carry the CTFd account identity (Authorization: Token <t> + account) so
+//     the server can VERIFY against CTFd's tokens→users tables — mirrors the
+//     gemini.ts / /api/icoa/audit auth so attribution is evidence, not a
+//     forgeable self-report.
+//   - Fire-and-forget: any failure is swallowed so the submit UX is untouched.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { getConfig, getBudget } from './config.js';
+import { getCliVersion } from './version.js';
+function readJsonFile(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fire a scrubbed integrity snapshot to the server. Best-effort, non-blocking,
+ * and self-swallowing — callers may `await` it inside an existing try/catch
+ * without risking the submit flow.
+ */
+export async function postIntegritySnapshot() {
+    try {
+        const config = getConfig();
+        // Gate: only sample during the live contest. Practice/learn traffic is
+        // non-scoring (§9) and carries no integrity interest.
+        if (config.competitionState !== 'live')
+            return;
+        const serverUrl = config.ctfdUrl;
+        if (!serverUrl)
+            return;
+        const icoaDir = join(homedir(), '.icoa');
+        const budget = getBudget();
+        // SCRUBBED payload — only client-only-knowable, non-secret state. The
+        // accessToken / token in config.json are deliberately NOT included.
+        const payload = {
+            deviceFingerprint: config.deviceFingerprint || '',
+            installSalt: config.installSalt || '',
+            budget: { tokensUsed: budget.tokensUsed, tokenCap: budget.tokenCap },
+            simCooldown: readJsonFile(join(icoaDir, 'sim-cooldown.json')),
+            tokenBindings: readJsonFile(join(icoaDir, 'token-bindings.json')),
+        };
+        const headers = {
+            'Content-Type': 'application/json',
+            'User-Agent': `icoa-cli/${getCliVersion()}`,
+            'X-Device-Fingerprint': config.deviceFingerprint || '',
+        };
+        // CTFd-account identity — same mechanism as gemini.ts. Only attach when
+        // connected to a CTFd event; the server VERIFIES the token in-process
+        // (account_verified=1) and falls back to the self-reported account only
+        // when it can't resolve.
+        if (config.token && config.userName) {
+            payload.account = config.userName;
+            headers.Authorization = `Token ${config.token}`;
+        }
+        await fetch(`${serverUrl}/api/icoa/snapshot`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(8000),
+        });
+        // Response intentionally ignored: detective-only, server reveals nothing.
+    }
+    catch {
+        // Swallow everything — the snapshot must never affect the submit UX.
+    }
+}

package/dist/lib/interactive-spawn.js

@@ -1 +1,55 @@
-import{spawn as e}from"node:child_process";import{getMainRl as t}from"./main-rl.js";export function runInteractive(o,s=[],i={}){return new Promise(r=>{const n=t(),c=process.stdin,a=!!c.isTTY&&!!c.isRaw;if(n?.pause(),c.isTTY&&"function"==typeof c.setRawMode)try{c.setRawMode(!1)}catch{}const f=i.shell?e(o,{shell:!0,stdio:"inherit"}):e(o,s,{stdio:"inherit"});let d=!1;const l=e=>{if(!d){if(d=!0,c.isTTY&&"function"==typeof c.setRawMode&&a)try{c.setRawMode(!0)}catch{}n?.resume(),r(e)}};f.on("close",e=>l(e??0)),f.on("error",()=>l(1))})}
+import { spawn } from 'node:child_process';
+import { getMainRl } from './main-rl.js';
+/**
+ * Run an interactive child process (nc / ncat / ssh) with the terminal fully
+ * released so the user's INPUT and Ctrl-C reach the child.
+ *
+ * Why this exists (BUG: pwn `connect` could read output but not send input and
+ * Ctrl-C was dead): when dispatched IN-PROCESS from the icoa REPL, the main
+ * readline holds stdin in RAW mode. A child spawned with `stdio: 'inherit'`
+ * then inherits a raw, non-blocking stdin → its reads see no keystrokes, and
+ * raw mode means Ctrl-C is delivered as a byte (0x03), never as SIGINT → the
+ * session looks frozen and won't quit. `execSync`/`execFileSync` never dropped
+ * raw mode, which is the bug.
+ *
+ * This mirrors repl.ts `runSystemCommand`'s proven TTY dance (pause the rl +
+ * `setRawMode(false)` + async spawn + restore), but pulls the active REPL
+ * readline via getMainRl() so it works BOTH inside the REPL and standalone
+ * (`icoa connect …`, where getMainRl() === null → pause/restore are no-ops).
+ *
+ * Pass a file + args (no shell — injection-safe, preferred for server-supplied
+ * host/port) OR set `shell: true` to run `file` as a full command string.
+ *
+ * Resolves with the child's exit code (1 on spawn error).
+ */
+export function runInteractive(file, args = [], opts = {}) {
+    return new Promise((resolve) => {
+        const rl = getMainRl();
+        const stdin = process.stdin;
+        const wasRaw = stdin.isTTY ? !!stdin.isRaw : false;
+        rl?.pause();
+        if (stdin.isTTY && typeof stdin.setRawMode === 'function') {
+            try {
+                stdin.setRawMode(false);
+            }
+            catch { }
+        }
+        const child = opts.shell ? spawn(file, { shell: true, stdio: 'inherit' }) : spawn(file, args, { stdio: 'inherit' });
+        let settled = false;
+        const restore = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (stdin.isTTY && typeof stdin.setRawMode === 'function' && wasRaw) {
+                try {
+                    stdin.setRawMode(true);
+                }
+                catch { }
+            }
+            rl?.resume();
+            resolve(code);
+        };
+        child.on('close', (code) => restore(code ?? 0));
+        child.on('error', () => restore(1));
+    });
+}

package/dist/lib/ipynb-input.js

@@ -1 +1,65 @@
-export function isBlockOpener(t){const e=t.split("#")[0];return/:\s*$/.test(e)}export function shouldExecuteCell(t){if(0===t.length)return!1;const e=t[t.length-1];return t.length>1?""===e.trim():!(""===e.trim()||isBlockOpener(e)||/\\\s*$/.test(e)||function(t){let e=0;for(const n of t)"("===n||"["===n||"{"===n?e++:")"!==n&&"]"!==n&&"}"!==n||e--;return e}(e)>0)}
+/**
+ * ipynb-input — pure cell-input decision logic for the `icoa ipynb` REPL
+ * (Phase 1 UI of the CLI notebook arena).
+ *
+ * IPython-style model: a one-liner runs the moment you press Enter; a block
+ * (def/for/if/…, an open bracket, or a trailing backslash) keeps accepting
+ * lines until you end it with a blank line. Kept pure so the rule is unit-
+ * tested without a kernel or readline.
+ */
+/**
+ * Does this line open a multi-line block? True when its CODE portion (trailing
+ * `#` comment stripped) ends with a colon. Naive comment-strip — good enough for
+ * opener detection (a real block opener never hides its colon in a comment).
+ */
+export function isBlockOpener(line) {
+    const code = line.split('#')[0];
+    return /:\s*$/.test(code);
+}
+/** Trailing line-continuation backslash. */
+function hasLineContinuation(line) {
+    return /\\\s*$/.test(line);
+}
+/**
+ * Count of unclosed brackets across the buffer. Naive: ignores brackets inside
+ * string literals (rare in interactive one-liners; a blank line always forces
+ * execution as the escape hatch). Positive → still open.
+ */
+function openBracketDepth(code) {
+    let depth = 0;
+    for (const ch of code) {
+        if (ch === '(' || ch === '[' || ch === '{')
+            depth++;
+        else if (ch === ')' || ch === ']' || ch === '}')
+            depth--;
+    }
+    return depth;
+}
+/**
+ * Given the lines accumulated SO FAR (including the just-entered line), decide
+ * whether to execute the cell now or keep taking input.
+ *
+ *  - empty buffer → nothing to run (false),
+ *  - multi-line cell → execute as soon as the last line is blank,
+ *  - single line → execute unless it opens a block / ends with `\` / has an
+ *    unbalanced bracket.
+ */
+export function shouldExecuteCell(lines) {
+    if (lines.length === 0)
+        return false;
+    const last = lines[lines.length - 1];
+    if (lines.length > 1) {
+        // In multi-line mode a blank line is the universal "run it now".
+        return last.trim() === '';
+    }
+    // Single line.
+    if (last.trim() === '')
+        return false;
+    if (isBlockOpener(last))
+        return false;
+    if (hasLineContinuation(last))
+        return false;
+    if (openBracketDepth(last) > 0)
+        return false;
+    return true;
+}

package/dist/lib/kernel-protocol.js

@@ -1 +1,88 @@
-const e=new Set(["ready","stream","result","display","error","done","fatal"]);export function parseKernelEvent(t){const a=t.trim();if(!a)return null;let r;try{r=JSON.parse(a)}catch{return null}if(!r||"object"!=typeof r)return null;const n=r.type;return"string"==typeof n&&e.has(n)?r:null}export function foldCellOutputs(e){const t=[];let a=!0,r=null;for(const n of e)switch(n.type){case"stream":{const e=t[t.length-1];e&&"stream"===e.kind&&e.name===n.name?e.text+=n.text:t.push({kind:"stream",name:n.name,text:n.text});break}case"result":t.push({kind:"result",text:n.text,...n.data?{data:n.data}:{}});break;case"display":t.push({kind:"display",data:n.data});break;case"error":a=!1,t.push({kind:"error",ename:n.ename,evalue:n.evalue,traceback:n.traceback});break;case"done":r=n.count;break;case"fatal":a=!1,t.push({kind:"error",ename:"KernelError",evalue:n.message,traceback:[n.message]})}return{outputs:t,ok:a,execCount:r}}
+/**
+ * Kernel protocol — the pure Node side of the Node ↔ Python-bridge boundary
+ * (Phase 1 of the CLI notebook arena, see `project_cli_notebook_arena_plan`).
+ *
+ * icoa is TypeScript/Node, but Jupyter kernels are driven by `jupyter_client`
+ * (Python). So a thin Python bridge (shipped alongside, run from the aienv
+ * venv) owns the kernel and speaks a line-delimited JSON protocol to Node: one
+ * event object per stdout line. This module parses those lines and folds them
+ * into renderable cell outputs.
+ *
+ * Keeping this layer pure (no I/O) means the wire contract is unit-tested
+ * without spawning Python — and it stays identical whether the bridge drives a
+ * LOCAL kernel (Phase 1) or a REMOTE one over a Kernel Gateway (Phase 2/4). The
+ * Node side never changes; only the bridge's connection does.
+ */
+const KNOWN_TYPES = new Set(['ready', 'stream', 'result', 'display', 'error', 'done', 'fatal']);
+/**
+ * Parse one stdout line from the bridge into a KernelEvent. Returns null for
+ * blank lines, non-JSON, or JSON without a recognized `type` (the bridge may
+ * interleave incidental output; we ignore anything not in the protocol).
+ */
+export function parseKernelEvent(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    let obj;
+    try {
+        obj = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (!obj || typeof obj !== 'object')
+        return null;
+    const type = obj.type;
+    if (typeof type !== 'string' || !KNOWN_TYPES.has(type))
+        return null;
+    return obj;
+}
+/**
+ * Fold a cell's event stream into renderable outputs.
+ *
+ *  - consecutive `stream` events of the SAME name coalesce into one text block
+ *    (matches Jupyter's stdout/stderr batching → clean rendering),
+ *  - `result` / `display` / `error` pass through as discrete blocks,
+ *  - any `error` sets ok=false,
+ *  - `done.count` becomes execCount (null if the cell never finished).
+ */
+export function foldCellOutputs(events) {
+    const outputs = [];
+    let ok = true;
+    let execCount = null;
+    for (const e of events) {
+        switch (e.type) {
+            case 'stream': {
+                const last = outputs[outputs.length - 1];
+                if (last && last.kind === 'stream' && last.name === e.name) {
+                    last.text += e.text;
+                }
+                else {
+                    outputs.push({ kind: 'stream', name: e.name, text: e.text });
+                }
+                break;
+            }
+            case 'result':
+                outputs.push({ kind: 'result', text: e.text, ...(e.data ? { data: e.data } : {}) });
+                break;
+            case 'display':
+                outputs.push({ kind: 'display', data: e.data });
+                break;
+            case 'error':
+                ok = false;
+                outputs.push({ kind: 'error', ename: e.ename, evalue: e.evalue, traceback: e.traceback });
+                break;
+            case 'done':
+                execCount = e.count;
+                break;
+            case 'fatal':
+                ok = false;
+                outputs.push({ kind: 'error', ename: 'KernelError', evalue: e.message, traceback: [e.message] });
+                break;
+            default:
+                // 'ready' and any future event types carry no cell output.
+                break;
+        }
+    }
+    return { outputs, ok, execCount };
+}