nou-cli 0.5.2 → 0.5.4

package/README.md

@@ -47,11 +47,13 @@ Needs **Node 22.12+** and an interactive terminal (Windows Terminal, PowerShell,
 | | |
 | --- | --- |
 | 🗂️ **File explorer** | Browse your project with file icons and git status (`M` modified, `?` new). Press <kbd>c</kbd> to see only changed files. |
-| 🔀 **Live diffs** | Every edit Nou proposes shows up side by side. <kbd>y</kbd> accepts, <kbd>n</kbd> rejects. Nothing touches disk without you. |
+| 🔀 **Live diffs** | Every edit Nou proposes shows up side by side, and the files it is editing shimmer in the file tree while it works. <kbd>y</kbd> accepts, <kbd>n</kbd> rejects. Nothing touches disk without you. |
 | ✍️ **Built-in editor** | Press <kbd>e</kbd> to edit the open file yourself, with undo/redo and **auto-save**. |
 | 📍 **Shows you where things are** | Ask "where is the LiveKit integration?" and Nou finds it and opens it in the middle panel, jumped to the exact lines and highlighted. Any file a reply mentions (`src/a.ts:12`) is a link: click it. `/open name[:line]` opens a file yourself. |
-| 🎮 **Games for a break** | Add Pong, Snake and Breakout in settings → Games, then `/games` opens a floating panel you can drag anywhere by its title. A game runs only while the panel has the keyboard: Esc goes back to your code and it waits. |
-| 🧠 **A capable engine** | Reads and searches in parallel, numbered reads for exact line references, edits that survive small whitespace mismatches, several edits to a file as one change, a plan for longer tasks, full command output (stderr too) with exit codes and timeouts, retries when a provider is overloaded, and conversation caching with Claude. It follows your repo's `AGENTS.md`, `CLAUDE.md` and `NOU.md` (and `~/.nou/NOU.md`). |
+| 🗂️ **Several agents at once** | `/new` (or **+** in the chat's title) opens another conversation tab while the first keeps working. Each tab has its own agent and history; a working tab shows ●, one waiting for your OK shows !, and a click (or `/tab 2`) switches. `/close` closes one; it stays in `/resume`. |
+| 🧑‍🏫 **Show me how** | `/showme add a --verbose flag` and Nou finds where the change goes, then walks you through typing it yourself: each step opens the file at the right line, says why, and shows the code to type dim ahead of your cursor, like autocomplete (<kbd>Tab</kbd> fills in a line). It moves on when what you typed matches, and saves as it goes. `/showme next` skips a step, `/showme stop` ends it. Works with every engine (Nou's, Claude Code, Codex and pi): any edit one makes anyway is put back. `/teach` does the same. |
+| 🎮 **Games for a break** | Add Pong, Snake and Breakout in settings → Games, then `/games` opens a panel docked under the chat: it splits that column instead of covering anything. Drag its title onto the files, code or chat to dock it there, and × at its top right closes it. Drag its top edge to make it taller or shorter. A game runs only while the panel has the keyboard: Esc goes back to your code and it waits. |
+| 🧠 **A capable engine** | Reads and searches in parallel, numbered reads for exact line references, edits that survive small whitespace mismatches, several edits to a file as one change, a plan for longer tasks, full command output (stderr too) with exit codes and timeouts, retries when a provider is overloaded or a connection drops (Codex too: it picks the turn back up instead of stopping at "Reconnecting..."), and conversation caching with Claude. It follows your repo's `AGENTS.md`, `CLAUDE.md` and `NOU.md` (and `~/.nou/NOU.md`). |
 | 🔎 **Finds its way around** | The agent searches your code (`grep`, `glob`) without asking, reads only what it needs, runs your tests to check its work, and summarizes long conversations to stay within the model's context (`/compact` does it on demand). |
 | ↶ **Undo anything** | Every change, Nou's or yours, is recorded. <kbd>u</kbd> undoes Nou's last edit, `/rewind` undoes its whole last turn, and your own later edits are kept. |
 | 🧾 **Session diffs** | `/diff` shows everything that changed this session, file by file (<kbd>[</kbd> <kbd>]</kbd> to step through). `/sessions` lists earlier sessions and `/diff 2` shows one. |
@@ -89,7 +91,7 @@ Every change is reviewed like a code review:
 | <kbd>Ctrl</kbd>+<kbd>P</kbd> | fuzzy-find a file; the files you've opened are listed first |
 | <kbd>b</kbd> | back to the previous file (press again to flip back) |
 | <kbd>Ctrl</kbd>+<kbd>F</kbd> | find in the open file: matches are highlighted and counted; <kbd>Enter</kbd>/<kbd>↓</kbd> next, <kbd>↑</kbd> previous, <kbd>Esc</kbd> close |
-| 🗂️ Tabs | every file you open gets a tab over the code: click one to switch, its × to close · <kbd>[</kbd>/<kbd>]</kbd> previous/next · <kbd>x</kbd> close |
+| 🗂️ Tabs | every file you open gets a tab over the code: click one to switch, any tab's × to close it, ‹ › for ones that don't fit · <kbd>[</kbd>/<kbd>]</kbd> previous/next · <kbd>x</kbd> or <kbd>Ctrl</kbd>+<kbd>W</kbd> close |
 | <kbd>Ctrl</kbd>+click | on a name in the code (or <kbd>Option</kbd>+click, or right-click): go to its definition; an imported name goes to its import, and the import's path opens that file |
 | <kbd>e</kbd> or a double-click | edit the open file (see the editor keys below) |
 | <kbd>p</kbd> | Problems panel: every error and warning, <kbd>Enter</kbd> jumps to it |
@@ -98,10 +100,12 @@ Every change is reviewed like a code review:
 | <kbd>c</kbd> | in the file tree: show only changed files |
 | <kbd>f</kbd> | follow mode (off by default): watch along as Nou works. Each file it reads (the exact lines, highlighted) is shown a step at a time, a little behind it, and its edits as they happen. The status bar shows how many steps behind it is; set the speed in settings → Preferences (slow · normal · fast · instant) |
 | <kbd>&lt;</kbd> / <kbd>&gt;</kbd> / <kbd>=</kbd> | make the focused pane narrower / wider / reset the layout |
-| <kbd>m</kbd> | mouse on/off, so you can select and copy text in the terminal |
+| <kbd>`</kbd> | a terminal under the code, like VS Code's (also `/terminal`): Enter runs a command, Ctrl+C stops it, ↑↓ history, Esc back to the code, × closes it; drag its top border (or <kbd>Alt</kbd>+↑/↓) to make it taller or shorter. Commands run through your shell one at a time, so full-screen programs like vim don't draw there |
+| <kbd>Ctrl</kbd>+<kbd>O</kbd> | in the chat: open or fold every "▸ N steps" line (what the agent read and ran between replies folds into one; click one to open just it) |
+| <kbd>m</kbd> | mouse on/off, so you can select and copy text in the terminal (in the chat, just drag over the text: it's copied when you let go) |
 | <kbd>s</kbd> | settings: model, preferences, plugins |
 | <kbd>y</kbd> / <kbd>n</kbd> | accept / reject a proposed edit or command, from any pane; the rest of Nou keeps working while it waits (<kbd>o</kbd> shows the edit) |
-| <kbd>Enter</kbd> while Nou works | queue the message: it goes when Nou finishes (<kbd>Alt</kbd>+<kbd>Enter</kbd>: stop Nou and send it now) |
+| <kbd>Enter</kbd> while Nou works | queue the message: it goes when Nou finishes, together with anything else you queued, as one message; commands that only change the screen, like `/terminal`, `/games` or `/open`, run right away (<kbd>Alt</kbd>+<kbd>Enter</kbd>: stop Nou and send it now) |
 | <kbd>Esc</kbd> | stop Nou (anything queued goes back in the input) · close a diff · back to chat |
 | <kbd>Ctrl</kbd>+<kbd>C</kbd> | stop Nou while it works · press twice to quit |
 
@@ -119,7 +123,11 @@ In the editor:
 | <kbd>Ctrl</kbd>+<kbd>K</kbd> · <kbd>Ctrl</kbd>+<kbd>G</kbd> | hover info · go to definition (with a language server) |
 | <kbd>Esc</kbd> | clear the selection, or leave the editor |
 
-Chat commands: `/settings` · `/model [provider:model]` · `/models [provider]` · `/pull <model>` · `/engine [name]` · `/auto [ask|auto-edit|auto]` · `/copy [code|file]` · `/undo` · `/rewind` · `/history` · `/diff [file or n]` · `/sessions` · `/problems` · `/compact` · `/clear` · `/help`
+Chat commands: `/settings` · `/model [provider:model]` · `/models [provider]` · `/pull <model>` · `/engine [name]` · `/auto [ask|auto-edit|auto]` · `/copy [code|file]` · `/undo` · `/rewind` · `/history` · `/diff [file or n]` · `/sessions` · `/problems` · `/compact` · `/clear` · `/resume [n|last]` · `/terminal` · `/showme <what you want>` · `/help`
+
+New lines in a message: <kbd>Shift</kbd>/<kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>Enter</kbd> in terminals that report them (kitty, Ghostty, WezTerm, iTerm2 and others with the kitty keyboard protocol), or type `\` and press <kbd>Enter</kbd> in any terminal.
+
+Conversations are saved per folder after each reply. `/resume` lists them and `/resume 2` (or `nou --continue` for the last one, `nou --resume` for the list) picks one back up with the engine it was on: Nou's own engine restores its messages, Claude Code its session and Codex its thread; pi is handed the conversation so far. Sessions you started in Claude Code's or Codex's own CLI in this folder are listed too (marked "CLI"), and resuming one carries it on in that engine inside Nou.
 
 ## 🧠 Models
 

package/dist/src/agent/index.js

@@ -16,10 +16,13 @@ function transient(error) {
         return true;
     if (status >= 400)
         return false;
-    const text = String(error?.message ?? error);
-    if (/ECONNREFUSED|ENOTFOUND|EAI_AGAIN|Invalid URL|api key|unauthori[sz]ed/i.test(text))
+    return transientMessage(String(error?.message ?? error));
+}
+/** Whether an error's text reads as a passing problem (a dropped stream, a busy or failing server). */
+export function transientMessage(text) {
+    if (/ECONNREFUSED|ENOTFOUND|EAI_AGAIN|Invalid URL|api key|unauthori[sz]ed|\b40[13]\b/i.test(text))
         return false;
-    return /overloaded|rate.?limit|too many requests|ECONNRESET|socket hang up|ETIMEDOUT|timed? ?out|EPIPE|network|premature close|terminated|\b(429|5\d\d)\b/i.test(text);
+    return /overloaded|rate.?limit|too many requests|ECONNRESET|socket hang up|ETIMEDOUT|timed? ?out|EPIPE|network|premature close|terminated|disconnected|server had an error|internal server error|service unavailable|bad gateway|try again|\b(429|5\d\d)\b/i.test(text);
 }
 /** Messages kept word for word when older ones are summarized. */
 const KEEP_RECENT = 8;
@@ -111,6 +114,24 @@ export class Agent {
         this.messages = [];
         this.notes = [];
     }
+    /** Forgets the last message you sent and everything after it, as if it was never sent. */
+    snapshot() {
+        return { messages: this.messages };
+    }
+    restore(state) {
+        if (!Array.isArray(state?.messages))
+            return false;
+        this.messages = state.messages;
+        this.forgetThinking(); // written in another run, maybe with another model
+        return true;
+    }
+    retractLast() {
+        const at = this.messages.findLastIndex((m) => m.role === "user");
+        if (at < 0)
+            return false;
+        this.messages = this.messages.slice(0, at);
+        return true;
+    }
     /** Something the model should know before the next message (e.g. the user undid its edit). */
     note(text) {
         this.notes.push(text);
@@ -254,8 +275,10 @@ export class Agent {
                     await this.compact(false, signal);
                 this.hooks.onBusy(`Pondering with ${describe(this.choice)}...`);
                 let streamed = "";
+                let thought = "";
                 const result = await this.withRetries(signal, () => {
                     streamed = "";
+                    thought = "";
                     return this.choice.provider.chat({
                         model: this.choice.model,
                         system: this.system,
@@ -267,6 +290,13 @@ export class Agent {
                             streamed += delta;
                             this.hooks.onStream(streamed);
                         },
+                        // Its thinking shows on the one-line progress (the latest of it), so the chat doesn't jump.
+                        onThinking: (delta) => {
+                            thought = (thought + delta).slice(-400);
+                            const latest = thought.split("\n").map((l) => l.trim()).filter(Boolean).at(-1) ?? "";
+                            if (latest)
+                                this.hooks.onBusy(`Thinking: ${latest.length > 90 ? `…${latest.slice(-89)}` : latest}`);
+                        },
                     });
                 });
                 this.hooks.onStream("");

package/dist/src/cli.js

@@ -18,6 +18,8 @@ const HELP = `nou ${currentVersion()}: an AI coding assistant for your terminal
 
 Usage:
   nou              open Nou in the current folder
+  nou --continue   pick up the last conversation in this folder (-c)
+  nou --resume     list earlier conversations here to pick one up (-r)
   nou update       update to the latest version
   nou --version    print the version
   nou --help       show this help
@@ -107,7 +109,7 @@ async function main() {
         await ensureProjectContext(choice);
     const permContext = await loadPermanentContext();
     await installFastOutput();
-    const app = render(createElement(App, { initialModel: choice, permContext }), RENDER_OPTIONS);
+    const app = render(createElement(App, { initialModel: choice, permContext, ...(args.includes("--continue") || args.includes("-c") ? { resume: "last" } : args.includes("--resume") || args.includes("-r") ? { resume: "list" } : {}) }), RENDER_OPTIONS);
     await app.waitUntilExit();
     lsp.stopAll();
     p.outro(chalk.cyan("Bye bye!"));

package/dist/src/commands/index.js

@@ -93,7 +93,7 @@ const OUTPUT_KEEP = 200_000;
 const running = new Set();
 let exitHooked = false;
 /** Stops a command and everything it started. */
-function stopProcess(child) {
+export function stopProcess(child) {
     try {
         if (process.platform === "win32") {
             if (child.pid)

package/dist/src/config/index.js

@@ -25,7 +25,9 @@ export const DEFAULT_SETTINGS = {
     paneWidths: null,
     trustedFolders: [],
     games: [],
-    gamePanel: null,
+    gameDock: "chat",
+    terminalRows: null,
+    gameRows: null,
     plugins: {},
     trustedPlugins: {},
 };

package/dist/src/conversations/external.js

@@ -0,0 +1,165 @@
+import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, statSync } from "fs";
+import os from "os";
+import path from "path";
+/** Files looked at per tool: the newest ones. */
+const SCAN = 300;
+const claudeDir = (home) => process.env.CLAUDE_CONFIG_DIR ?? path.join(home, ".claude");
+const codexDir = (home) => process.env.CODEX_HOME ?? path.join(home, ".codex");
+function jsonLines(file, limit = Infinity) {
+    const out = [];
+    let text;
+    try {
+        text = readFileSync(file, "utf-8");
+    }
+    catch {
+        return out;
+    }
+    for (const line of text.split("\n")) {
+        if (out.length >= limit)
+            break;
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // a line being written
+        }
+    }
+    return out;
+}
+/** The start of a file, for the line that says which folder a Codex session ran in. */
+function head(file, bytes = 8192) {
+    const fd = openSync(file, "r");
+    try {
+        const buf = Buffer.alloc(bytes);
+        return buf.subarray(0, readSync(fd, buf, 0, bytes, 0)).toString("utf-8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Plain text from a message's content (a string, or parts with text). */
+function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content.filter((p) => typeof p?.text === "string" && /^(text|input_text|output_text)$/.test(p.type ?? "text")).map((p) => p.text).join("\n");
+}
+/** What the tools add on their own (context blocks, command echoes): not something you typed. */
+const injected = (text) => /^\s*<(environment_context|user_instructions|command-|local-command|system-reminder)/.test(text) || text.startsWith("Caveat:");
+const titleOf = (text) => text.replace(/\s+/g, " ").trim().slice(0, 80);
+/** Claude Code's sessions for this folder. */
+function claudeSessions(home, cwd) {
+    const dir = path.join(claudeDir(home), "projects", cwd.replace(/[^A-Za-z0-9]/g, "-"));
+    if (!existsSync(dir))
+        return [];
+    const files = readdirSync(dir).filter((f) => f.endsWith(".jsonl")).map((f) => path.join(dir, f));
+    const out = [];
+    for (const file of newest(files)) {
+        const said = claudeEntries(file);
+        const first = said.find((e) => e.kind === "user");
+        if (!first)
+            continue;
+        out.push({ id: path.basename(file, ".jsonl"), engine: "claude-code", title: titleOf(first.text), updated: statSync(file).mtimeMs, messages: said.filter((e) => e.kind === "user").length, file });
+    }
+    return out;
+}
+function claudeEntries(file) {
+    const out = [];
+    for (const line of jsonLines(file)) {
+        if (line.isSidechain || line.isMeta)
+            continue;
+        if (line.type === "user" && line.message?.role === "user") {
+            const text = textOf(line.message.content);
+            if (text.trim() && !injected(text))
+                out.push({ kind: "user", text: text.trim() });
+        }
+        else if (line.type === "assistant") {
+            const text = textOf(line.message?.content);
+            if (text.trim())
+                out.push({ kind: "assistant", text: text.trim() });
+        }
+    }
+    return out;
+}
+/** Codex's sessions for this folder (it keeps them all in one tree, by date). */
+function codexSessions(home, cwd) {
+    const root = path.join(codexDir(home), "sessions");
+    if (!existsSync(root))
+        return [];
+    const files = [];
+    const walk = (dir, depth) => {
+        for (const name of readdirSync(dir).sort().reverse()) {
+            if (files.length >= SCAN)
+                return;
+            const full = path.join(dir, name);
+            if (depth < 3)
+                walk(full, depth + 1);
+            else if (name.startsWith("rollout-") && name.endsWith(".jsonl"))
+                files.push(full);
+        }
+    };
+    try {
+        walk(root, 0);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const file of files) {
+        let meta;
+        try {
+            meta = JSON.parse(head(file).split("\n")[0]);
+        }
+        catch {
+            continue;
+        }
+        const payload = meta?.type === "session_meta" ? meta.payload : null;
+        if (!payload?.id || path.resolve(payload.cwd ?? "") !== path.resolve(cwd))
+            continue;
+        const said = codexEntries(file);
+        const first = said.find((e) => e.kind === "user");
+        if (!first)
+            continue;
+        out.push({ id: payload.id, engine: "codex", title: titleOf(first.text), updated: statSync(file).mtimeMs, messages: said.filter((e) => e.kind === "user").length, file });
+    }
+    return out;
+}
+function codexEntries(file) {
+    const out = [];
+    for (const line of jsonLines(file)) {
+        const p = line.type === "response_item" ? line.payload : null;
+        if (p?.type !== "message")
+            continue;
+        const text = textOf(p.content).trim();
+        if (!text || injected(text))
+            continue;
+        if (p.role === "user")
+            out.push({ kind: "user", text });
+        else if (p.role === "assistant")
+            out.push({ kind: "assistant", text });
+    }
+    return out;
+}
+function newest(files) {
+    return files.map((f) => ({ f, t: statSync(f).mtimeMs })).sort((a, b) => b.t - a.t).slice(0, SCAN).map((x) => x.f);
+}
+/** Claude Code's and Codex's own sessions in this folder, latest first. */
+export function externalSessions(home = os.homedir(), cwd = process.cwd()) {
+    const out = [];
+    for (const read of [claudeSessions, codexSessions]) {
+        try {
+            out.push(...read(home, cwd));
+        }
+        catch {
+            // a tool's files we can't read: skip them
+        }
+    }
+    return out.sort((a, b) => b.updated - a.updated);
+}
+/** The chat of an external session, to show when it's resumed. */
+export function externalEntries(session) {
+    return session.engine === "claude-code" ? claudeEntries(session.file) : codexEntries(session.file);
+}

package/dist/src/conversations/index.js

@@ -0,0 +1,71 @@
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import path from "path";
+import { NOU_HOME } from "../config/index.js";
+/** Kept per project: the oldest go once there are more. */
+const KEEP = 50;
+/** Chat entries saved per conversation (the latest ones). */
+const MAX_ENTRIES = 500;
+function folder(cwd = process.cwd()) {
+    const name = path.basename(cwd).replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 40);
+    return path.join(NOU_HOME, "conversations", `${name}-${createHash("sha1").update(cwd).digest("hex").slice(0, 10)}`);
+}
+export function saveConversation(conversation) {
+    const dir = folder();
+    try {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const entries = conversation.entries.slice(-MAX_ENTRIES);
+        writeFileSync(path.join(dir, `${conversation.id}.json`), JSON.stringify({ ...conversation, entries }), { mode: 0o600 });
+        const old = listConversations().slice(KEEP);
+        for (const c of old)
+            unlinkSync(path.join(dir, `${c.id}.json`));
+    }
+    catch {
+        // Saving is a convenience: a read-only home shouldn't break the chat.
+    }
+}
+/** This project's conversations, latest first. */
+export function listConversations() {
+    const dir = folder();
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const file of readdirSync(dir)) {
+        if (!file.endsWith(".json"))
+            continue;
+        try {
+            const c = JSON.parse(readFileSync(path.join(dir, file), "utf-8"));
+            const state = c.state;
+            const ref = state?.claudeSession ?? state?.codexThread;
+            out.push({ id: c.id, title: c.title, updated: c.updated, engine: c.engine, messages: c.entries.filter((e) => e.kind === "user").length, ...(typeof ref === "string" ? { ref } : {}) });
+        }
+        catch {
+            // a damaged file is skipped
+        }
+    }
+    return out.sort((a, b) => b.updated - a.updated);
+}
+export function loadConversation(id) {
+    if (!/^[A-Za-z0-9_-]+$/.test(id))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path.join(folder(), `${id}.json`), "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** "5m ago", "yesterday"... */
+export function ago(time, now = Date.now()) {
+    const s = Math.max(0, Math.round((now - time) / 1000));
+    if (s < 60)
+        return "just now";
+    if (s < 3600)
+        return `${Math.floor(s / 60)}m ago`;
+    if (s < 86_400)
+        return `${Math.floor(s / 3600)}h ago`;
+    if (s < 172_800)
+        return "yesterday";
+    return `${Math.floor(s / 86_400)}d ago`;
+}

package/dist/src/engines/claude.js

@@ -50,6 +50,16 @@ export class ClaudeCodeEngine extends ExternalEngine {
     resetConversation() {
         this.claudeSession = undefined;
     }
+    snapshot() {
+        return this.claudeSession ? { claudeSession: this.claudeSession } : undefined;
+    }
+    /** Claude Code keeps its sessions on disk, so a saved one resumes in a later run too. */
+    restore(state) {
+        if (typeof state?.claudeSession !== "string")
+            return false;
+        this.claudeSession = state.claudeSession;
+        return true;
+    }
     /** Claude Code can resume its session with another model, so the conversation carries over. */
     setModel(choice) {
         this.choice = choice;

package/dist/src/engines/codex.js

@@ -1,11 +1,14 @@
 import { execFileSync } from "child_process";
 import { statSync } from "fs";
+import { transientMessage } from "../agent/index.js";
 import { listAllFiles } from "../ui/QuickOpen.js";
 import { ExternalEngine } from "./external.js";
 import { loadPackage } from "./index.js";
 const EFFORTS = new Set(["low", "medium", "high", "xhigh", "max"]);
 const MAX_FILES = 5000;
 const MAX_BYTES = 512 * 1024;
+/** Times a turn that failed for a passing reason (a dropped stream, a failing server) is picked up again. */
+const RESUMES = 5;
 /** Project files small enough to keep a copy of (git's list when there is one, so ignored files are skipped). */
 function projectFiles() {
     let files;
@@ -42,34 +45,82 @@ export class CodexEngine extends ExternalEngine {
     id = "codex";
     thread = null;
     introduced = false;
+    /** A saved thread to pick back up (/resume): Codex keeps its threads on disk. */
+    resumeId;
     constructor(choice, hooks) {
         super(choice, hooks, "Codex");
     }
     resetConversation() {
         this.thread = null;
         this.introduced = false;
+        this.resumeId = undefined;
+    }
+    snapshot() {
+        const id = this.thread?.id ?? this.resumeId;
+        return id ? { codexThread: id } : undefined;
+    }
+    restore(state) {
+        if (typeof state?.codexThread !== "string")
+            return false;
+        this.thread = null;
+        this.resumeId = state.codexThread;
+        this.introduced = true; // it already has the project context
+        return true;
     }
     async run(prompt, signal) {
         const { Codex } = await loadPackage("@openai/codex-sdk");
         // Codex uses its own login (`codex login`); an OpenAI key from Nou's setup works too.
         const apiKey = process.env.CODEX_API_KEY || process.env.OPENAI_API_KEY;
-        this.thread ??= new Codex(apiKey ? { apiKey } : {}).startThread({
+        const options = {
             workingDirectory: process.cwd(),
             skipGitRepoCheck: true,
             sandboxMode: "workspace-write",
+            // Its sandbox blocks the network by default, so npm/pip installs and tests that fetch fail ("can't
+            // resolve registry.npmjs.org"); Nou's other engines can reach it, so Codex can too.
+            networkAccessEnabled: true,
             approvalPolicy: "never",
             ...(this.choice.provider.id === "openai" ? { model: this.choice.model } : {}),
             ...(this.effort && EFFORTS.has(this.effort) ? { modelReasoningEffort: this.effort } : {}),
-        });
+        };
+        const codex = new Codex(apiKey ? { apiKey } : {});
+        this.thread ??= this.resumeId ? codex.resumeThread(this.resumeId, options) : codex.startThread(options);
         // Codex has no system prompt option; Nou's project context goes with the first message.
         const input = !this.introduced && this.extras.length ? `${this.extras.join("\n\n")}\n\n${prompt}` : prompt;
         this.introduced = true;
         this.tracker.remember(projectFiles());
+        // Codex retries a dropped stream itself ("Reconnecting... 2/5"); when it gives up, Nou picks the turn up
+        // again on the same thread, waiting longer each time, before calling it failed.
+        for (let attempt = 0;; attempt++) {
+            const failure = await this.runTurn(attempt ? "The connection dropped before you finished. Carry on where you left off." : input, signal);
+            if (!failure)
+                return;
+            if (attempt >= RESUMES || !transientMessage(failure))
+                throw new Error(explain(failure));
+            const wait = Math.min(30_000, 2000 * 2 ** attempt);
+            this.hooks.onStream("");
+            this.hooks.onBusy(`Codex: ${failure.split("\n")[0].slice(0, 70)}. Retrying in ${wait / 1000}s (${attempt + 1}/${RESUMES})...`);
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, wait);
+                signal.addEventListener("abort", () => (clearTimeout(timer), resolve()), { once: true });
+            });
+            if (signal.aborted)
+                throw new Error("aborted");
+        }
+    }
+    /** Runs one Codex turn; returns why it failed, if it did. */
+    async runTurn(input, signal) {
         let failure;
         try {
             const { events } = await this.thread.runStreamed(input, { signal });
-            for await (const event of events)
+            for await (const event of events) {
+                if (event.type === "turn.completed") {
+                    // Its turn is over (it may have just asked you something): done now, rather than waiting for the
+                    // codex process to wind down, which kept "Codex is working..." up under its question.
+                    failure = undefined; // and it recovered from anything that went wrong on the way
+                    break;
+                }
                 failure = (await this.handle(event)) ?? failure;
+            }
         }
         catch (error) {
             // The codex process exiting with an error ends the stream; its first line says why.
@@ -79,8 +130,7 @@ export class CodexEngine extends ExternalEngine {
         }
         if (signal.aborted)
             throw new Error("aborted");
-        if (failure)
-            throw new Error(explain(failure));
+        return failure;
     }
     /** Shows one Codex event; returns the error message if the turn failed. */
     async handle(event) {
@@ -124,6 +174,11 @@ export class CodexEngine extends ExternalEngine {
             return event.error.message;
         }
         else if (event.type === "error") {
+            // "Reconnecting... 1/5 (stream disconnected ...)": Codex is retrying, so it's progress, not the end.
+            if (/^Reconnecting\b/i.test(event.message)) {
+                this.hooks.onBusy(`Codex: ${event.message.split("\n")[0].slice(0, 100)}`);
+                return undefined;
+            }
             return event.message;
         }
         return undefined;

package/dist/src/guide/index.js

@@ -0,0 +1,100 @@
+import path from "path";
+export const SHOW_STEPS = "show_steps";
+/** The tool the engine hands its steps back with. `onSteps` gets them; the engine is told they're shown. */
+export function showStepsTool(onSteps) {
+    return {
+        definition: {
+            name: SHOW_STEPS,
+            description: "Only when the user asked you to show them how ([Show me how] in their message): hand back the change as steps for them to type themselves, instead of editing. Each step adds whole lines of code before a line of a file, with why it's needed. Call it once, with every step in order.",
+            parameters: {
+                type: "object",
+                properties: {
+                    steps: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                file: { type: "string", description: "Project-relative path of the file to add to." },
+                                line: { type: "number", description: "1-based line the code goes in before (the line after the last one appends)." },
+                                code: { type: "string", description: "The lines to type, indented as they'll be in the file." },
+                                why: { type: "string", description: "One or two plain sentences: what this does and why it's needed." },
+                            },
+                            required: ["file", "line", "code", "why"],
+                        },
+                    },
+                },
+                required: ["steps"],
+            },
+        },
+        readOnly: true,
+        source: "nou",
+        run: (args) => {
+            const steps = tidySteps(args.steps);
+            if (!steps.length)
+                return "No usable steps: each needs a file, a line and the code to type. Call show_steps again.";
+            onSteps(steps);
+            return `Shown to the user as ${steps.length} step${steps.length > 1 ? "s" : ""} to type. Don't edit the files yourself; finish with a one-line summary.`;
+        },
+    };
+}
+/** Steps as the model gave them, kept when usable: a file, a line, code to type. */
+function tidySteps(raw) {
+    return (Array.isArray(raw) ? raw : [])
+        .filter((s) => typeof s?.file === "string" && typeof s?.code === "string" && s.code.trim())
+        .map((s) => ({ file: path.relative(process.cwd(), path.resolve(s.file)).split(path.sep).join("/"), line: Math.max(1, Math.floor(Number(s.line) || 1)), code: s.code.replace(/\r\n/g, "\n").replace(/\n+$/, ""), why: String(s.why ?? "") }));
+}
+/** The fenced block other engines (which can't call Nou's tools) put their steps in. */
+const BLOCK = /```nou-steps\s*\n([\s\S]*?)\n```/;
+/**
+ * The message that asks for steps. Nou's own engine hands them back with the show_steps tool; Claude
+ * Code, Codex and pi can't call Nou's tools, so they end their reply with a ```nou-steps block instead.
+ */
+export function showMePrompt(task, withTool) {
+    const how = withTool
+        ? `call ${SHOW_STEPS} once with the steps in order`
+        : "end your reply with the steps in order as a JSON array in a fenced block marked nou-steps, like:\n```nou-steps\n[{\"file\": \"src/cli.ts\", \"line\": 12, \"code\": \"const verbose = args.includes(\\\"--verbose\\\");\", \"why\": \"Reads the new flag.\"}]\n```";
+    return `[Show me how] ${task}\n\nDon't edit any files: I want to type it myself. Read what you need to find where it goes, then ${how} (each step: file, the line to add the code before, the exact lines of code to type, and why). Keep each step small, a few lines, so it's easy to follow.`;
+}
+/** Steps from a reply's ```nou-steps block, and the reply without it; null when there's none. */
+export function stepsFromReply(text) {
+    const m = BLOCK.exec(text);
+    if (!m)
+        return null;
+    try {
+        const steps = tidySteps(JSON.parse(m[1]));
+        return steps.length ? { steps, rest: text.replace(m[0], "").trim() } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * How far the text typed so far (`typed`, from where the step starts to the cursor) gets through
+ * `expected`: the index reached in `expected`, or -1 when it doesn't match. Leading indentation on each
+ * line is ignored either way, since the editor indents new lines itself.
+ */
+export function guideProgress(typed, expected) {
+    let i = 0;
+    let j = 0;
+    const skipIndent = (s, k) => {
+        while (k < s.length && (s[k] === " " || s[k] === "\t"))
+            k++;
+        return k;
+    };
+    i = skipIndent(typed, i);
+    j = skipIndent(expected, j);
+    while (i < typed.length) {
+        if (j >= expected.length || typed[i] !== expected[j])
+            return -1;
+        const newline = typed[i] === "\n";
+        i++;
+        j++;
+        if (newline) {
+            i = skipIndent(typed, i);
+            // The rest of the expected indentation counts as typed only once something follows it.
+            if (i < typed.length)
+                j = skipIndent(expected, j);
+        }
+    }
+    return j;
+}