nou-cli 0.2.1 → 0.4.0

package/.env.example

@@ -6,6 +6,12 @@
 
 # --- Local ---
 # OLLAMA_HOST=http://127.0.0.1:11434
+# Ollama context window. By default Nou asks for 32k tokens (or the model's max, if smaller),
+# unless the model's Modelfile sets num_ctx. Lower it if you run out of memory.
+# NOU_NUM_CTX=16384
+# How much conversation (in characters, ~4 per token) Nou keeps before trimming and summarizing it.
+# Defaults: 90000 for local models, 500000 for cloud ones. Lower it if a local model loses track.
+# NOU_CONTEXT_CHARS=90000
 # LMSTUDIO_BASE_URL=http://localhost:1234/v1
 # LLAMACPP_BASE_URL=http://localhost:8080/v1
 # Any other OpenAI-compatible server (vLLM, Jan, LocalAI, ...):
@@ -19,6 +25,13 @@
 # OPENROUTER_API_KEY=
 # GROQ_API_KEY=
 # DEEPSEEK_API_KEY=
+# FIREWORKS_API_KEY=
+# A LiteLLM proxy, or any hosted OpenAI-compatible gateway (full cloud context, unlike NOU_BASE_URL):
+# LITELLM_BASE_URL=http://localhost:4000/v1
+# LITELLM_API_KEY=
+# (LITELLM_PROXY_API_BASE and LITELLM_PROXY_API_KEY, the names LiteLLM's SDK uses, work too.)
+# NOU_MODEL=litellm:<a model name from your proxy>
+# Or skip this file: /connect <provider> inside Nou saves keys to ~/.nou/credentials.json.
 
 # Claude effort level: low | medium | high | xhigh | max (default high)
 # NOU_EFFORT=high

package/README.md

@@ -15,7 +15,7 @@
   <img src="https://img.shields.io/badge/Claude-cloud-bb9af7?style=flat-square&logo=anthropic&logoColor=white&labelColor=1a1b26" alt="Claude">
   <img src="https://img.shields.io/badge/OpenAI-cloud-bb9af7?style=flat-square&labelColor=1a1b26" alt="OpenAI">
   <img src="https://img.shields.io/badge/Gemini-cloud-bb9af7?style=flat-square&logo=googlegemini&logoColor=white&labelColor=1a1b26" alt="Gemini">
-  <img src="https://img.shields.io/badge/OpenRouter%20·%20Groq%20·%20DeepSeek-cloud-bb9af7?style=flat-square&labelColor=1a1b26" alt="More providers">
+  <img src="https://img.shields.io/badge/OpenRouter%20·%20Groq%20·%20DeepSeek%20·%20Fireworks%20·%20LiteLLM-cloud-bb9af7?style=flat-square&labelColor=1a1b26" alt="More providers">
 </p>
 
 <p align="center">
@@ -38,7 +38,7 @@ nou
 ```
 
 > [!TIP]
-> Want it fully local and free? Install [Ollama](https://ollama.com), run `ollama pull qwen3:8b`, and you're set. That's the default model.
+> Want it fully local and free? Just run `nou`: if Ollama or its model (`qwen3:8b`) is missing, Nou offers to install and download them. Already using Claude Code or Codex with an API key, or have Ollama models or LM Studio? Nou finds them on first run and lets you pick.
 
 Needs **Node 22.12+** and an interactive terminal (Windows Terminal, PowerShell, macOS/Linux terminals).
 
@@ -49,7 +49,9 @@ 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. |
 | ✍️ **Built-in editor** | Press <kbd>e</kbd> to edit the open file yourself, with undo/redo and **auto-save**. |
+| 🔎 **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. |
 | 🩺 **Problems, live** | Syntax errors instantly, plus ESLint, TypeScript, Ruff and language servers when your project has them. Shown in the gutter, inline, and in a <kbd>p</kbd> Problems panel. |
 | 🤖 **Self-correcting** | Nou checks its own edits: you see "⚠ +1 problem" *before* approving, and any problems it introduced are fed back so it fixes them. |
 | 🎨 **Real syntax highlighting** | tree-sitter parsing for 14 languages (TS, JS, Python, Go, Rust, Java, C, JSON, YAML…). |
@@ -57,6 +59,7 @@ Needs **Node 22.12+** and an interactive terminal (Windows Terminal, PowerShell,
 | 👀 **Knows what you're looking at** | The open file, visible lines, your cursor and unsaved edits ride along with each message. "Fix this function" just works. |
 | 🌿 **Git aware** | Sees your branch, uncommitted changes and recent commits, and can diff on its own. Press <kbd>v</kbd> to diff any file against `HEAD`. |
 | 🔌 **Any model** | Local (Ollama, LM Studio, llama.cpp) or cloud (Claude, OpenAI, Gemini, OpenRouter, Groq, DeepSeek). Switch mid-conversation. |
+| 🛞 **Pick your agent** | Nou's own, or Claude Code, Codex or pi, switchable like models, with the same diffs, approvals and undo. |
 | 🧩 **Plugins** | Add your own tools and slash commands with a single file. |
 | 🔎 **Quick open** | <kbd>Ctrl</kbd>+<kbd>P</kbd> fuzzy-finds any file. |
 
@@ -73,26 +76,31 @@ Every change is reviewed like a code review:
 
 | Key | Does |
 | --- | --- |
-| 🖱️ Mouse | wheel scrolls the pane under the pointer · click a pane to focus it · click a file to open it (hold <kbd>Shift</kbd> to select text; turn off in settings) |
+| 🖱️ Mouse | wheel scrolls the pane under the pointer · click a pane to focus it · click a file to open it · drag a border between panes to resize them (hold <kbd>Shift</kbd> to select text, or press <kbd>m</kbd> to turn the mouse off) |
 | <kbd>Shift</kbd>+<kbd>↑</kbd>/<kbd>↓</kbd>, <kbd>PgUp</kbd>/<kbd>PgDn</kbd> | scroll the chat history |
 | <kbd>Tab</kbd> | switch between files, code and chat |
+| <kbd>Shift</kbd>+<kbd>Tab</kbd> | ask → auto-edit (edits apply without asking) → auto (commands too); everything stays undoable |
 | <kbd>Ctrl</kbd>+<kbd>P</kbd> | fuzzy-find a file |
 | <kbd>e</kbd> | edit the open file (<kbd>Ctrl</kbd>+<kbd>S</kbd> save · <kbd>Ctrl</kbd>+<kbd>Z</kbd>/<kbd>Y</kbd> undo/redo · <kbd>Ctrl</kbd>+<kbd>K</kbd> info · <kbd>Ctrl</kbd>+<kbd>G</kbd> definition · <kbd>Esc</kbd> close) |
 | <kbd>p</kbd> | Problems panel: every error and warning, <kbd>Enter</kbd> jumps to it |
 | <kbd>u</kbd> | undo Nou's last edit |
-| <kbd>v</kbd> | diff the open file vs git `HEAD` (or Nou's last edit) · <kbd>n</kbd>/<kbd>N</kbd> jump between changes |
+| <kbd>v</kbd> | diff the open file vs git `HEAD`, Nou's last edit, or this session · <kbd>n</kbd>/<kbd>N</kbd> jump between changes · <kbd>[</kbd>/<kbd>]</kbd> previous/next file in a session diff |
 | <kbd>c</kbd> | in the file tree: show only changed files |
-| <kbd>f</kbd> | follow mode: jump to files as Nou reads and edits them |
+| <kbd>f</kbd> | follow mode (off by default): jump to files as Nou reads and edits them |
+| <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>s</kbd> | settings: model, preferences, plugins |
-| <kbd>y</kbd> / <kbd>n</kbd> | accept / reject a proposed edit or command |
+| <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>Esc</kbd> | stop Nou · close a diff · back to chat |
 | <kbd>Ctrl</kbd>+<kbd>C</kbd> | stop Nou while it works · press twice to quit |
 
-Chat commands: `/settings` · `/model [provider:model]` · `/models [provider]` · `/undo` · `/rewind` · `/history` · `/problems` · `/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` · `/help`
 
 ## 🧠 Models
 
-Pick one in <kbd>s</kbd> settings, with `/model anthropic` or `/model ollama:qwen3:8b`, or set `NOU_MODEL=provider:model`. API keys come from your environment or a `.env` file in your project; see [.env.example](.env.example).
+Pick one in <kbd>s</kbd> settings, with `/model anthropic` or `/model ollama:qwen3:8b`, or set `NOU_MODEL=provider:model`. Switching to an Ollama model you don't have downloads it (or use `/pull <model>`). API keys come from your environment or a `.env` file in your project; see [.env.example](.env.example). Or connect a provider inside Nou: pick it in <kbd>s</kbd> settings and press <kbd>Enter</kbd>, or run `/connect fireworks`, then paste your key. It's saved to `~/.nou/credentials.json` (only you can read it) and works right away, no restart. If a key is rejected, settings says where it came from (your shell, `.env`, or Claude Code's or Codex's settings); press <kbd>k</kbd> to enter another.
+
+If you haven't set a key, Nou uses the API key from Claude Code (`~/.claude/settings.json`) or Codex (`~/.codex/auth.json`). Subscription sign-ins (claude.ai, ChatGPT) can't be reused. Turn this off in settings with "Use Claude Code / Codex keys".
 
 <details>
 <summary><b>All providers and how to set them up</b></summary>
@@ -103,15 +111,34 @@ Pick one in <kbd>s</kbd> settings, with `/model anthropic` or `/model ollama:qwe
 | 🖥️ LM Studio | 🟢 local | start its local server |
 | ⚙️ llama.cpp server | 🟢 local | start `llama-server` |
 | 🔧 Any OpenAI-compatible server | 🟢 local | `NOU_BASE_URL`, optional `NOU_API_KEY` |
+| 🚅 LiteLLM proxy or any hosted gateway | ☁️ cloud | `/connect litellm`, or `LITELLM_BASE_URL` + `LITELLM_API_KEY` (LiteLLM's `LITELLM_PROXY_API_BASE` + `LITELLM_PROXY_API_KEY` work too) |
 | 🟣 Anthropic (Claude) | ☁️ cloud | `ANTHROPIC_API_KEY` |
-| ⚪ OpenAI | ☁️ cloud | `OPENAI_API_KEY` |
+| ⚪ OpenAI | ☁️ cloud | `OPENAI_API_KEY`, optional `OPENAI_BASE_URL` |
 | 🔷 Google Gemini | ☁️ cloud | `GEMINI_API_KEY` |
 | 🔀 OpenRouter | ☁️ cloud | `OPENROUTER_API_KEY` |
 | ⚡ Groq | ☁️ cloud | `GROQ_API_KEY` |
 | 🐋 DeepSeek | ☁️ cloud | `DEEPSEEK_API_KEY` |
+| 🎆 Fireworks AI | ☁️ cloud | `/connect fireworks`, or `FIREWORKS_API_KEY` |
+
+Every cloud provider can also be connected from inside Nou with `/connect <provider>`.
+
+**Local or cloud?** Nou keeps less conversation for local models (about 90k characters) before summarizing, since they usually run with a small context window. The `custom` provider is meant for servers on your machine (vLLM, Jan, LocalAI...). For a LiteLLM proxy, or any other OpenAI-compatible gateway in front of cloud models, use `litellm`: it gets the full cloud budget. Override either with `NOU_CONTEXT_CHARS`.
 
 </details>
 
+## 🛞 Engines
+
+The engine is the agent that answers in the chat. Nou's own works with every model; you can switch to another one any time, like switching models: <kbd>s</kbd> settings → **Engine**, or `/engine <name>`. Diffs, approvals, undo and the problems panel work with all of them.
+
+| Engine | Models | Asks before edits and commands |
+|:--|:--|:--:|
+| `nou` *(default)* | any | ✅ |
+| `claude-code` (Claude Agent SDK) | Claude; your API key or Claude login | ✅ |
+| `pi` | your Nou model, local or cloud | ✅ |
+| `codex` (Codex SDK) | OpenAI; your API key or ChatGPT login | ❌ edits in its sandbox; review and undo after |
+
+Other engines install on first use into `~/.nou/engines/`, so Nou itself stays small. Switching engines starts a new conversation. Compare them on the same tasks with `npm run eval -- --engine nou --engine claude-code`.
+
 ## 🔄 Updating
 
 Nou checks npm once a day and offers to update when a new version is out (one keypress, then it restarts itself). Or run it yourself:
@@ -125,7 +152,16 @@ Set `NOU_NO_UPDATE_CHECK=1` to turn the check off.
 
 ## 🧩 Plugins *(early)*
 
-Drop a `.js` / `.mjs` file into `.nou/plugins/` (this project) or `~/.nou/plugins/` (everywhere), then switch it on in <kbd>s</kbd> settings → **Plugins**. A plugin can give the model new tools, add slash commands, add to the system prompt, and add **checkers** (linters) whose problems show in the editor. The built-in ESLint, TypeScript, Ruff, syntax and language-server checkers are plugins too, so you can switch any of them off.
+**Starter plugins** ship with Nou and are optional: open <kbd>s</kbd> settings → **Plugins** and press Enter on one, or type `/plugins add <name>`. Adding one copies it into `~/.nou/plugins/`, where it's yours to edit.
+
+| Starter | What it adds |
+|:--|:--|
+| `run-tests` | `run_tests` tool and `/test`. Works out npm / pnpm / yarn / bun, cargo, go, pytest or make (asks before each run). |
+| `todos` | `find_todos` tool and `/todos`: TODO / FIXME / HACK comments with file:line. |
+| `fetch-url` | `fetch_url` tool so the model can read docs and web pages (asks before each URL). |
+| `project-rules` | Feeds `AGENTS.md`, `CLAUDE.md`, `.cursorrules` and Copilot instructions to the model; `/rules` lists them. |
+
+**Write your own:** `/plugins new <name>` creates a commented `.nou/plugins/<name>.mjs` to fill in. `/plugins` lists what you have. Or drop a `.js` / `.mjs` file into `.nou/plugins/` (this project) or `~/.nou/plugins/` (everywhere), then switch it on in <kbd>s</kbd> settings → **Plugins**. A plugin can give the model new tools, add slash commands, add to the system prompt, and add **checkers** (linters) whose problems show in the editor. The built-in ESLint, TypeScript, Ruff, syntax and language-server checkers are plugins too, so you can switch any of them off.
 
 ```js
 export default {
@@ -153,6 +189,7 @@ npm run dev          # run from source
 npm run build        # compile to dist/ (and copy the syntax grammars)
 npm test             # end-to-end tests: drives the real UI with simulated keys
 npm run screenshot   # regenerate docs/screenshot.svg
+npm run eval         # how well the agent does real tasks with a real model (see evals/)
 ```
 
 Releasing: bump `version` in `package.json`, merge to `master`, then run **Actions → Publish to npm**. It tests, publishes with provenance, and creates the git tag and GitHub Release. (Or publish a GitHub release tagged `vX.Y.Z`.) The token lives in the `production` environment as `NPM_TOKEN`.

package/dist/index.js

@@ -7,7 +7,10 @@ import * as p from "@clack/prompts";
 import chalk from "chalk";
 import { artWork } from "./src/util/index.js";
 import { ensureProjectContext, loadPermanentContext } from "./src/context/index.js";
-import { describe, initialModel, resolveModel } from "./src/providers/index.js";
+import { describe, initialModel, resolveModel, saveModel } from "./src/providers/index.js";
+import { loadSettings } from "./src/config/index.js";
+import { loadCredentials } from "./src/config/credentials.js";
+import { borrowToolConfig, ensureLocalModel, pickStartingModel } from "./src/setup/index.js";
 import { checkForUpdate, currentVersion, installUpdate, relaunch } from "./src/update/index.js";
 import { lsp } from "./src/lsp/index.js";
 import { App } from "./src/ui/App.js";
@@ -19,7 +22,7 @@ Usage:
   nou --version    print the version
   nou --help       show this help
 
-Settings live in ~/.nou/config.json (or press s inside Nou). Set NOU_NO_UPDATE_CHECK=1 to skip update checks.`;
+Settings live in ~/.nou/config.json (or press s inside Nou); keys you enter there, or with /connect, in ~/.nou/credentials.json. Set NOU_NO_UPDATE_CHECK=1 to skip update checks.`;
 async function main() {
     const args = process.argv.slice(2);
     if (args.includes("--version") || args.includes("-v")) {
@@ -63,12 +66,29 @@ async function main() {
                 : "The update failed. If it was a permissions error, run: sudo npm install -g nou-cli@latest");
         }
     }
+    const settings = loadSettings();
+    loadCredentials(); // keys entered inside Nou, for whatever the environment and .env leave unset
+    const borrowed = settings.reuseToolConfig ? borrowToolConfig() : [];
+    for (const b of borrowed)
+        p.log.info(`Using the ${b.provider === "anthropic" ? "Anthropic" : "OpenAI"} API key from your ${b.tool} settings.`);
     let choice = initialModel();
+    // First run: start with a model that's already here, if there is one.
+    if (!process.env.NOU_MODEL && !settings.model) {
+        const picked = await pickStartingModel(borrowed);
+        if (picked) {
+            choice = picked;
+            saveModel(picked);
+        }
+    }
     const problem = choice.provider.unavailable();
     if (problem) {
         p.log.warn(`${choice.provider.label} isn't set up (${problem}), falling back to local Ollama.`);
         choice = resolveModel("ollama");
     }
+    const ready = await ensureLocalModel(choice);
+    if (ready !== choice)
+        saveModel(ready); // picked a model that's already installed instead
+    choice = ready;
     p.log.info(`Model: ${chalk.yellow(describe(choice))}  (change it any time with /model)`);
     await ensureProjectContext(choice);
     const permContext = await loadPermanentContext();

package/dist/src/agent/harness.js

@@ -0,0 +1,54 @@
+import { formatDiagnostic } from "../diagnostics/index.js";
+import { summary as gitSummary } from "../git/index.js";
+import { gitTools } from "../git/tools.js";
+/**
+ * Everything the agent gets on top of the built-in tools: git context and tools, plugin prompts and tools,
+ * and the problems checker. Shared by the app and the evals, so evals measure exactly what users get.
+ */
+export function harness(options) {
+    const { diagnostics, plugins, git } = options;
+    const extras = [];
+    const extraTools = [];
+    if (git) {
+        const summary = gitSummary();
+        if (summary)
+            extras.push(summary);
+        extraTools.push(...gitTools());
+    }
+    for (const plugin of plugins) {
+        if (plugin.systemPrompt)
+            extras.push(`Plugin ${plugin.name}: ${plugin.systemPrompt}`);
+        for (const tool of plugin.tools ?? []) {
+            extraTools.push({
+                definition: tool.definition,
+                readOnly: !!tool.readOnly,
+                source: plugin.name,
+                run: (args) => tool.run(args, { cwd: process.cwd() }),
+            });
+        }
+    }
+    extraTools.push({
+        source: "problems",
+        readOnly: true,
+        definition: {
+            name: "get_diagnostics",
+            description: "Get errors and warnings from the project's linters, type checker and language servers, for one file or the whole project.",
+            parameters: { type: "object", properties: { path: { type: "string", description: "Optional file. Omit for the whole project." } }, required: [] },
+        },
+        run: async (args) => {
+            const file = typeof args.path === "string" ? args.path : null;
+            if (file)
+                await diagnostics.checkFile(file);
+            else
+                await diagnostics.checkProject();
+            const list = file ? diagnostics.get(file) : diagnostics.all();
+            return list.length ? list.slice(0, 100).map((d) => formatDiagnostic(d, true)).join("\n") : "No problems found.";
+        },
+    });
+    return { extras, extraTools };
+}
+/** Problems an applied edit introduced, to feed back to the model (the agent's checkChange hook). */
+export async function problemsIntroduced(diagnostics, change) {
+    const introduced = await diagnostics.introducedBy(change.path, change.before, change.after);
+    return introduced.length ? introduced.slice(0, 15).map((d) => formatDiagnostic(d)).join("\n") : null;
+}

package/dist/src/agent/index.js

@@ -1,17 +1,34 @@
+import { randomUUID } from "crypto";
 import { toolDefs } from "../tools/index.js";
-import { applyChange, fileTree, proposeEdit, proposeWrite, readFile, runCommand, toRelative, } from "../commands/index.js";
-import { describe } from "../providers/index.js";
+import { applyChange, capOutput, fileTree, isInProject, proposeEdit, proposeWrite, readForModel, runCommand, toRelative, } from "../commands/index.js";
+import { describe, keyHint } from "../providers/index.js";
 import { newCallId } from "../providers/ids.js";
-const MAX_STEPS = 25;
+import { globFiles, grep } from "../search/index.js";
+/** Model requests per user message before stopping; real tasks (explore, edit, test, fix) take a few dozen. */
+const MAX_STEPS = 60;
+/** Messages kept word for word when older ones are summarized. */
+const KEEP_RECENT = 8;
+const TRIMMED_OUTPUT = "\n[... trimmed to save context; run the tool again if you need it]";
+/** Unique per conversation, since turn numbers restart at 1 every session. */
+export const newSessionId = () => `${Date.now().toString(36)}${randomUUID().slice(0, 8)}`;
+/** How many lines of the project tree go in the system prompt; the model can glob or list_files for more. */
+const PROMPT_TREE_LINES = 150;
 export function buildSystemPrompt(permContext, extras = []) {
-    return `You are Nou, a coding assistant running in the user's terminal, working in ${process.cwd()}.
-You can read, edit and create files and run commands with the tools you have.
-- Read a file before editing it. Prefer edit_file for small changes and write_file for new files.
-- Every edit and command is shown to the user, who approves or rejects it.
-- Keep replies short and to the point.
+    const shell = process.platform === "win32" ? "Windows (commands run in cmd.exe)" : `${process.platform} (commands run in sh)`;
+    return `You are Nou, a coding agent in the user's terminal. You work in ${process.cwd()} on ${shell}.
+
+How to work:
+1. Look before you change anything. Use grep to find where things are defined and used, glob to find files by name, and read_file for the parts you need. Never guess what a file contains.
+2. Make the smallest change that does what was asked, in the style of the surrounding code. Use edit_file for changes, copying old_string exactly from what you read (replace_all renames every occurrence in a file). Use write_file only for new files or complete rewrites.
+3. Check your work. If the project has tests, a build or a type check, run them with run_command and fix what you broke. If it has none, try new code on the examples the user gave (a one-line script is enough). Problems the editor finds after an edit are reported back to you: fix them.
+4. Keep going until the task is done. The user approves each edit and command as it happens, so don't stop to ask permission between steps; ask only when the request is unclear or you need a decision.
+5. End with a short summary of what you changed and why. When the user only asks a question, answer it without editing anything.
+
+- If the user rejects an edit or command, don't retry it: ask what they would like instead.
+- Keep replies short. Refer to code as path:line.
 
 Project files:
-${fileTree(".", 3)}
+${fileTree(".", 3, PROMPT_TREE_LINES)}
 ${extras.map((e) => `\n${e}`).join("")}
 ${permContext}`;
 }
@@ -25,10 +42,12 @@ function invalidArgs(call, tools) {
     const missing = def.parameters.required.filter((key) => call.args[key] === undefined || call.args[key] === null);
     return missing.length ? `Missing or non-string arguments: ${missing.join(", ")}` : null;
 }
+/** Nou's own engine: its tools, prompt and loop, with any model. */
 export class Agent {
     choice;
     system;
     hooks;
+    id = "nou";
     messages = [];
     controller = null;
     extraTools = [];
@@ -37,7 +56,7 @@ export class Agent {
     /** Increments per user message; tags changes so a whole turn can be rewound. */
     turn = 0;
     /** Distinguishes this run from earlier ones, since turn numbers restart at 1 every session. */
-    session = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+    session = newSessionId();
     get turnId() {
         return `${this.session}:${this.turn}`;
     }
@@ -72,6 +91,104 @@ export class Agent {
     cancel() {
         this.controller?.abort();
     }
+    /** Roughly what each request sends, in characters (about 4 per token): prompt, tool schemas and history. */
+    requestSize() {
+        return this.system.length + JSON.stringify(this.tools).length + JSON.stringify(this.messages).length;
+    }
+    /**
+     * How much context to stay under, in characters. Local models get a 32k-token window from Nou (see
+     * providers/ollama.ts), so ~90k characters leaves room for the reply; cloud models have far more.
+     */
+    contextBudget() {
+        const set = Number(process.env.NOU_CONTEXT_CHARS);
+        if (set > 0)
+            return set;
+        return this.choice.provider.local ? 90_000 : 500_000;
+    }
+    /**
+     * Makes the conversation fit the model's context: first trims old tool output (the bulk of it, and
+     * rarely needed again), then, if that isn't enough, has the model summarize older messages. `force`
+     * (the /compact command) summarizes even when it fits. Returns whether anything changed.
+     */
+    async compact(force = false, signal) {
+        const budget = this.contextBudget();
+        const startSize = this.requestSize();
+        // The latest step's results are what the model is working from; it has already used the older ones.
+        const lastStep = this.messages.findLastIndex((m) => m.role === "assistant");
+        let trimmed = 0;
+        for (let i = 0; i < lastStep; i++) {
+            const m = this.messages[i];
+            if (m.role === "tool" && m.content.length > TRIMMED_OUTPUT.length + 400) {
+                this.messages[i] = { ...m, content: `${m.content.slice(0, 300)}${TRIMMED_OUTPUT}` };
+                trimmed++;
+            }
+        }
+        if (!force && this.requestSize() <= budget * 0.8) {
+            this.hooks.onEntry({ kind: "info", text: `Trimmed ${trimmed} old tool outputs to fit the model's context.` });
+            return true;
+        }
+        const split = this.summarySplit();
+        if (split <= 0)
+            return trimmed > 0;
+        this.hooks.onBusy("Summarizing the conversation to fit the model's context...");
+        let summary;
+        try {
+            summary = await this.summarize(this.messages.slice(0, split), signal);
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            summary = `(The earlier conversation was dropped to fit the context; summarizing it failed: ${error.message})`;
+        }
+        const intro = `[Summary of the conversation so far]\n${summary}`;
+        const rest = this.messages.slice(split);
+        const first = rest[0];
+        this.messages = first?.role === "user"
+            ? [{ ...first, content: `${intro}\n\n${first.content}` }, ...rest.slice(1)]
+            : [{ role: "user", content: intro }, ...rest];
+        this.hooks.onEntry({
+            kind: "info",
+            text: `Summarized ${split} earlier messages to fit the model's context (${Math.round(startSize / 1000)}k → ${Math.round(this.requestSize() / 1000)}k characters).`,
+        });
+        return true;
+    }
+    /**
+     * Where to cut the history for a summary: as late as possible while keeping the last few messages, and
+     * only before a user or assistant message, so no tool call is separated from its result.
+     */
+    summarySplit() {
+        for (let i = this.messages.length - KEEP_RECENT; i > 0; i--) {
+            if (this.messages[i]?.role !== "tool")
+                return i;
+        }
+        return 0;
+    }
+    async summarize(older, signal) {
+        const clip = (text, max) => (text.length > max ? `${text.slice(0, max)}...` : text);
+        const transcript = older.map((m) => {
+            if (m.role === "user")
+                return `USER: ${clip(m.content, 4000)}`;
+            if (m.role === "tool")
+                return `TOOL RESULT (${m.name}): ${clip(m.content, 600)}`;
+            const calls = m.toolCalls.map((c) => `${c.name}(${clip(JSON.stringify(c.args), 300)})`).join(", ");
+            return `ASSISTANT: ${clip(m.content, 2000)}${calls ? `\n  called: ${calls}` : ""}`;
+        }).join("\n\n");
+        // Keep the request itself within budget: the latest part of the history matters most.
+        const room = Math.floor(this.contextBudget() * 0.7);
+        const text = transcript.length > room ? `[...]\n${transcript.slice(-room)}` : transcript;
+        const result = await this.choice.provider.chat({
+            model: this.choice.model,
+            system: "You summarize a coding session so it can continue with less context. Be factual and concise.",
+            messages: [{
+                    role: "user",
+                    content: `Summarize this conversation between a user and a coding agent, for the agent to continue from. Include: the user's requests (quote the latest one exactly), decisions made, files read or changed and what changed, commands run and their outcome, and what is left to do.\n\n${text}`,
+                }],
+            tools: [],
+            onText: () => { },
+            ...(signal ? { signal } : {}),
+        });
+        return result.text.replace(/<think>[\s\S]*?<\/think>\s*/g, "").trim() || "(no summary)";
+    }
     /** `context` (what the user is looking at) is sent to the model but not shown in the chat. */
     async send(text, context) {
         this.turn++;
@@ -82,6 +199,8 @@ export class Agent {
         const { signal } = this.controller;
         try {
             for (let step = 0; step < MAX_STEPS; step++) {
+                if (this.requestSize() > this.contextBudget())
+                    await this.compact(false, signal);
                 this.hooks.onBusy(`Pondering with ${describe(this.choice)}...`);
                 let streamed = "";
                 const result = await this.choice.provider.chat({
@@ -108,7 +227,8 @@ export class Agent {
                 }
                 this.messages.push({
                     role: "assistant",
-                    content: result.text,
+                    // Local reasoning models think in <think> blocks; sending those back only uses up context.
+                    content: result.raw ? result.text : result.text.replace(/<think>[\s\S]*?<\/think>\s*/g, ""),
                     toolCalls: result.toolCalls,
                     ...(result.raw ? { raw: result.raw } : {}),
                 });
@@ -132,7 +252,7 @@ export class Agent {
                         break;
                     this.hooks.onBusy(`Running ${call.name}...`);
                     const problem = invalidArgs(call, this.tools);
-                    const output = problem ?? await this.runTool(call);
+                    const output = problem ?? capOutput(await this.runTool(call));
                     this.messages.push({
                         role: "tool",
                         callId: call.id,
@@ -152,7 +272,8 @@ export class Agent {
                 this.hooks.onEntry({ kind: "info", text: "Cancelled." });
             }
             else {
-                this.hooks.onEntry({ kind: "error", text: `${describe(this.choice)}: ${error.message}` });
+                const hint = keyHint(this.choice.provider, String(error.message));
+                this.hooks.onEntry({ kind: "error", text: `${describe(this.choice)}: ${error.message}${hint ? `\n${hint}` : ""}` });
             }
             this.dropUnansweredCalls();
         }
@@ -180,19 +301,43 @@ export class Agent {
         try {
             switch (name) {
                 case "read_file": {
-                    this.hooks.onRead(toRelative(args.path));
+                    // Files outside the project (e.g. ~/.ssh) need your OK, like commands do.
+                    if (!isInProject(args.path)) {
+                        if (!(await this.hooks.approve({ kind: "tool", name, args }))) {
+                            this.hooks.onEntry({ kind: "tool", text: `Denied: read ${args.path}` });
+                            return "User denied reading this file: it is outside the project folder.";
+                        }
+                    }
+                    else {
+                        this.hooks.onRead(toRelative(args.path));
+                    }
                     this.hooks.onEntry({ kind: "tool", text: `Read ${args.path}` });
-                    return await readFile(args.path);
+                    return await readForModel(args.path, args.offset, args.limit);
                 }
                 case "list_files":
                 case "get_file_tree": {
                     this.hooks.onEntry({ kind: "tool", text: `Listed ${args.path ?? "."}` });
-                    return fileTree(args.path ?? ".", 4);
+                    return fileTree(args.path ?? ".", 4, 500);
+                }
+                case "grep": {
+                    this.hooks.onEntry({ kind: "tool", text: `Searched for ${args.pattern}${args.path ? ` in ${args.path}` : ""}${args.glob ? ` (${args.glob})` : ""}` });
+                    return grep({
+                        pattern: String(args.pattern),
+                        ...(typeof args.path === "string" ? { path: args.path } : {}),
+                        ...(typeof args.glob === "string" ? { glob: args.glob } : {}),
+                        ignoreCase: args.ignore_case === true,
+                        context: Number(args.context) || 0,
+                        filesOnly: args.files_only === true,
+                    });
+                }
+                case "glob": {
+                    this.hooks.onEntry({ kind: "tool", text: `Found files ${args.pattern}` });
+                    return globFiles(String(args.pattern), typeof args.path === "string" ? args.path : ".");
                 }
                 case "edit_file":
                 case "write_file": {
                     const change = name === "edit_file"
-                        ? await proposeEdit(args.path, args.old_string, args.new_string)
+                        ? await proposeEdit(args.path, args.old_string, args.new_string, args.replace_all === true)
                         : await proposeWrite(args.path, args.content ?? "");
                     return await this.reviewChange(change);
                 }

package/dist/src/commands/index.js

@@ -3,6 +3,11 @@ import fs from "fs/promises";
 import { readdirSync } from "fs";
 import { exec } from "child_process";
 export const IGNORED = new Set(["node_modules", ".git", "dist", "build", ".next", "__pycache__", ".venv"]);
+/** Whether a path is inside the project folder (where Nou may read without asking and write at all). */
+export function isInProject(filePath) {
+    const rel = path.relative(process.cwd(), path.resolve(process.cwd(), filePath));
+    return !rel.startsWith("..") && !path.isAbsolute(rel);
+}
 function resolveInProject(filePath) {
     const fullPath = path.resolve(process.cwd(), filePath);
     const rel = path.relative(process.cwd(), fullPath);
@@ -25,6 +30,41 @@ export async function readFile(filepath) {
     }
 }
 ;
+/** Lines read_file returns by default, and the most characters it returns at once. */
+export const READ_LINES = 1000;
+const READ_CHARS = 40_000;
+/**
+ * read_file for the model: a window of lines (1-based `offset`), with a note saying how to read on when the
+ * file is longer, so a big file can't flood the model's context.
+ */
+export async function readForModel(filePath, offset = 1, limit = READ_LINES) {
+    const text = await fs.readFile(path.resolve(process.cwd(), filePath), "utf-8");
+    const lines = text.split(/\r?\n/);
+    if (lines.length > 1 && lines.at(-1) === "")
+        lines.pop();
+    const start = Math.max(1, Math.floor(offset) || 1);
+    if (start > lines.length)
+        return `(The file has ${lines.length} lines.)`;
+    let end = Math.min(lines.length, start + Math.max(1, Math.floor(limit) || READ_LINES) - 1);
+    if (start === 1 && end === lines.length && text.length <= READ_CHARS)
+        return text;
+    let body = lines.slice(start - 1, end).join("\n");
+    if (body.length > READ_CHARS) {
+        body = body.slice(0, READ_CHARS);
+        end = start + body.split("\n").length - 1;
+        body = `${body}\n[... line ${end} cut off: it is very long]`;
+    }
+    const more = end < lines.length ? ` Read more with offset=${end + 1}.` : "";
+    return `${body}\n\n[Lines ${start}-${end} of ${lines.length}.${more}]`;
+}
+/** Keeps tool output a sensible size for the model: the start and, where errors usually are, the end. */
+export function capOutput(text, max = 40_000) {
+    if (text.length <= max)
+        return text;
+    const head = Math.floor(max / 3);
+    const tail = max - head;
+    return `${text.slice(0, head)}\n\n[... ${text.length - max} characters cut ...]\n\n${text.slice(-tail)}`;
+}
 export function runCommand(command) {
     // Async so the UI keeps rendering while the command runs.
     return new Promise((resolve) => {
@@ -40,8 +80,9 @@ ${stdout}` : ""}`);
         });
     });
 }
-export function fileTree(dir = ".", maxDepth = 3) {
+export function fileTree(dir = ".", maxDepth = 3, maxLines = Infinity) {
     const lines = [];
+    let hidden = 0;
     const walk = (current, depth, prefix) => {
         if (depth > maxDepth)
             return;
@@ -55,12 +96,18 @@ export function fileTree(dir = ".", maxDepth = 3) {
             return;
         }
         for (const entry of entries) {
+            if (lines.length >= maxLines) {
+                hidden++;
+                continue;
+            }
             lines.push(`${prefix}${entry.name}${entry.isDirectory() ? "/" : ""}`);
             if (entry.isDirectory())
                 walk(path.join(current, entry.name), depth + 1, prefix + "  ");
         }
     };
     walk(path.resolve(process.cwd(), dir), 1, "");
+    if (hidden)
+        lines.push("[... more entries not shown; use glob, grep or list_files on a folder]");
     return lines.join("\n") || "(empty)";
 }
 /**
@@ -95,7 +142,7 @@ export async function proposeWrite(filePath, content) {
     return { path: toRelative(filePath), before: before ?? "", after: cleanContent(content), isNew: before === null };
 }
 /** Works out what edit_file would do, without touching the disk. */
-export async function proposeEdit(filePath, oldString, newString) {
+export async function proposeEdit(filePath, oldString, newString, replaceAll = false) {
     const fullPath = resolveInProject(filePath);
     const before = await readOrEmpty(fullPath);
     if (before === null)
@@ -107,9 +154,11 @@ export async function proposeEdit(filePath, oldString, newString) {
     const count = target ? normalized.split(target).length - 1 : 0;
     if (count === 0)
         throw new Error("old_string was not found in the file. Read the file and copy the text exactly.");
-    if (count > 1)
-        throw new Error(`old_string appears ${count} times. Include more surrounding lines so it is unique.`);
-    const after = normalized.replace(target, () => newString.replace(/\r\n/g, "\n")).replace(/\n/g, eol);
+    if (count > 1 && !replaceAll) {
+        throw new Error(`old_string appears ${count} times. Include more surrounding lines so it is unique, or set replace_all to change every one.`);
+    }
+    const replacement = newString.replace(/\r\n/g, "\n");
+    const after = (replaceAll ? normalized.split(target).join(replacement) : normalized.replace(target, () => replacement)).replace(/\n/g, eol);
     return { path: toRelative(filePath), before, after, isNew: false };
 }
 export async function applyChange(change) {