nou-cli 0.2.1 → 0.4.0

package/dist/src/config/credentials.js

@@ -0,0 +1,48 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import path from "path";
+import { NOU_HOME } from "./index.js";
+import { noteOrigin } from "./origins.js";
+/**
+ * API keys and base URLs you enter inside Nou (settings → Model, or /connect), saved as env var name -> value.
+ * They fill in only what your environment and .env leave unset, so those always win.
+ */
+const CREDENTIALS_PATH = path.join(NOU_HOME, "credentials.json");
+function readSaved() {
+    try {
+        const saved = JSON.parse(readFileSync(CREDENTIALS_PATH, "utf-8"));
+        return Object.fromEntries(Object.entries(saved).filter((e) => typeof e[1] === "string" && !!e[1]));
+    }
+    catch {
+        return {};
+    }
+}
+/** Fills in saved keys and URLs for anything not already set. Call before choosing a model. */
+export function loadCredentials() {
+    for (const [name, value] of Object.entries(readSaved())) {
+        if (process.env[name])
+            continue;
+        process.env[name] = value;
+        noteOrigin([name], "Nou (~/.nou/credentials.json)");
+    }
+}
+/** Saves keys and URLs (readable only by you) and applies them to this session. Empty values are skipped. */
+export function saveCredentials(values) {
+    const next = readSaved();
+    for (const [name, value] of Object.entries(values)) {
+        const trimmed = value.trim();
+        if (!trimmed)
+            continue;
+        next[name] = trimmed;
+        process.env[name] = trimmed;
+        noteOrigin([name], "Nou (~/.nou/credentials.json)");
+    }
+    if (!existsSync(NOU_HOME))
+        mkdirSync(NOU_HOME, { recursive: true });
+    writeFileSync(CREDENTIALS_PATH, JSON.stringify(next, null, 2), { mode: 0o600 });
+    try {
+        chmodSync(CREDENTIALS_PATH, 0o600); // the mode above only applies when the file is created
+    }
+    catch {
+        // Windows ignores it
+    }
+}

package/dist/src/config/index.js

@@ -7,13 +7,16 @@ export const EFFORTS = ["low", "medium", "high", "xhigh", "max"];
 export const AUTO_SAVE = ["delay", "focus", "off"];
 export const DEFAULT_SETTINGS = {
     model: "",
+    engine: "nou",
     effort: "high",
-    followMode: true,
+    followMode: false,
     autoApproveEdits: false,
     autoApproveCommands: false,
     gitContext: true,
     autoSave: "delay",
     mouse: true,
+    reuseToolConfig: true,
+    paneWidths: null,
     plugins: {},
     trustedPlugins: {},
 };

package/dist/src/config/origins.js

@@ -0,0 +1,14 @@
+/** Where each API key or URL came from (env var name -> e.g. ".env"), so a rejected key can say where to fix it. */
+const origins = new Map();
+export function noteOrigin(names, origin) {
+    for (const name of names)
+        origins.set(name, origin);
+}
+/** Where a setting came from, or undefined if it isn't set. */
+export function originOf(name) {
+    if (!process.env[name])
+        return undefined;
+    return origins.get(name) ?? "your environment";
+}
+/** Whether it was set outside Nou (your shell or .env), where it wins over a key saved in Nou on the next start. */
+export const setOutsideNou = (name) => ["your environment", ".env"].includes(originOf(name) ?? "");

package/dist/src/context/index.js

@@ -47,7 +47,7 @@ export async function loadPermanentContext() {
         const content = await fs.readFile(contextPath, "utf-8");
         return `\n\nPROJECT SPECIFIC RULES (from NOU.md):\n${content}`;
     }
-    catch (err) {
+    catch {
         return "";
     }
 }

package/dist/src/engines/claude.js

@@ -0,0 +1,147 @@
+import { readFileSync } from "fs";
+import path from "path";
+import { toRelative } from "../commands/index.js";
+import { ExternalEngine, replaceIn } from "./external.js";
+import { loadPackage } from "./index.js";
+const EFFORTS = new Set(["low", "medium", "high", "xhigh", "max"]);
+/** Claude Code tools that change files; Nou previews and approves them. */
+const EDIT_TOOLS = new Set(["Edit", "MultiEdit", "Write", "NotebookEdit"]);
+function current(filePath) {
+    try {
+        return readFileSync(path.resolve(process.cwd(), filePath), "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/** The file's content after a Claude Code edit, or undefined if it can't be worked out in advance. */
+export function proposedContent(tool, input) {
+    if (tool === "Write")
+        return String(input.content ?? "");
+    const before = current(input.file_path);
+    if (before === null)
+        return undefined;
+    if (tool === "Edit")
+        return replaceIn(before, input.old_string, input.new_string, input.replace_all === true) ?? undefined;
+    if (tool === "MultiEdit" && Array.isArray(input.edits)) {
+        let text = before;
+        for (const edit of input.edits)
+            text = text === null ? null : replaceIn(text, edit.old_string, edit.new_string, edit.replace_all === true);
+        return text ?? undefined;
+    }
+    return undefined;
+}
+/** A short line for the chat about a tool Claude Code ran. */
+function describeTool(tool, input) {
+    const target = input.file_path ?? input.path ?? input.pattern ?? input.url ?? input.query ?? input.description ?? "";
+    return `${tool}${target ? ` ${typeof target === "string" && input.file_path ? toRelative(target) : target}` : ""}`;
+}
+/**
+ * Claude Code through the Claude Agent SDK. Its PreToolUse hook sends every edit and command to Nou's
+ * approval (with a diff for edits); PostToolUse records what changed for undo and feeds problems back.
+ */
+export class ClaudeCodeEngine extends ExternalEngine {
+    id = "claude-code";
+    /** Claude Code's session, resumed for each message so the conversation carries on. */
+    claudeSession;
+    constructor(choice, hooks) {
+        super(choice, hooks, "Claude Code");
+    }
+    resetConversation() {
+        this.claudeSession = undefined;
+    }
+    /** Claude Code can resume its session with another model, so the conversation carries over. */
+    setModel(choice) {
+        this.choice = choice;
+    }
+    async run(prompt, signal) {
+        const sdk = await loadPackage("@anthropic-ai/claude-agent-sdk");
+        const abortController = new AbortController();
+        signal.addEventListener("abort", () => abortController.abort());
+        const allow = { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow" } };
+        const deny = (reason) => ({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } });
+        const preToolUse = async (input) => {
+            const tool = input.tool_name;
+            const args = (input.tool_input ?? {});
+            if (EDIT_TOOLS.has(tool) && args.file_path) {
+                const ok = await this.tracker.approve(args.file_path, proposedContent(tool, args), tool);
+                return ok ? allow : deny("The user rejected this change. Ask them what they would like instead.");
+            }
+            if (tool === "Bash" || tool === "PowerShell") {
+                const ok = await this.hooks.approve({ kind: "command", command: String(args.command ?? "") });
+                if (!ok)
+                    this.hooks.onEntry({ kind: "tool", text: `Denied: ${args.command}` });
+                return ok ? allow : deny("The user denied permission to run this command.");
+            }
+            // Reads and searches follow Claude Code's own rules; anything else that needs asking reaches canUseTool.
+            return {};
+        };
+        const postToolUse = async (input) => {
+            const tool = input.tool_name;
+            const args = (input.tool_input ?? {});
+            if (EDIT_TOOLS.has(tool) && args.file_path) {
+                const problems = await this.tracker.applied(args.file_path);
+                return problems
+                    ? { hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: `This edit introduced problems; fix them:\n${problems}` } }
+                    : {};
+            }
+            if (tool === "Read" && args.file_path)
+                this.hooks.onRead(toRelative(args.file_path));
+            this.hooks.onEntry({ kind: "tool", text: tool === "Bash" || tool === "PowerShell" ? `Ran: ${args.command}` : describeTool(tool, args) });
+            return {};
+        };
+        const query = sdk.query({
+            prompt,
+            options: {
+                cwd: process.cwd(),
+                abortController,
+                ...(this.claudeSession ? { resume: this.claudeSession } : {}),
+                ...(this.choice.provider.id === "anthropic" ? { model: this.choice.model } : {}),
+                ...(this.effort && EFFORTS.has(this.effort) ? { effort: this.effort } : {}),
+                includePartialMessages: true,
+                // Ask for everything not explicitly allowed, so Nou's approvals apply; project settings bring CLAUDE.md.
+                permissionMode: "default",
+                settingSources: ["project"],
+                systemPrompt: { type: "preset", preset: "claude_code", append: this.extras.join("\n\n") },
+                hooks: { PreToolUse: [{ hooks: [preToolUse] }], PostToolUse: [{ hooks: [postToolUse] }] },
+                canUseTool: async (tool, input) => {
+                    const ok = await this.hooks.approve({ kind: "tool", name: tool, args: input });
+                    if (!ok)
+                        this.hooks.onEntry({ kind: "tool", text: `Denied: ${describeTool(tool, input)}` });
+                    return ok ? { behavior: "allow", updatedInput: input } : { behavior: "deny", message: "The user denied this." };
+                },
+            },
+        });
+        let streamed = "";
+        for await (const message of query) {
+            if (message.type === "system" && message.subtype === "init") {
+                this.claudeSession = message.session_id;
+            }
+            else if (message.type === "stream_event" && !message.parent_tool_use_id) {
+                const event = message.event;
+                if (event.type === "content_block_delta" && event.delta?.type === "text_delta") {
+                    streamed += event.delta.text;
+                    this.hooks.onStream(streamed);
+                }
+            }
+            else if (message.type === "assistant" && !message.parent_tool_use_id) {
+                const text = message.message.content.filter((b) => b.type === "text").map((b) => b.text).join("").trim();
+                streamed = "";
+                this.hooks.onStream("");
+                if (text)
+                    this.hooks.onEntry({ kind: "assistant", text });
+                this.hooks.onBusy("Claude Code is working...");
+            }
+            else if (message.type === "result") {
+                this.claudeSession = message.session_id ?? this.claudeSession;
+                if (message.subtype !== "success" || message.is_error) {
+                    const detail = message.errors?.join("; ") || message.result || message.subtype;
+                    if (!signal.aborted)
+                        this.hooks.onEntry({ kind: "error", text: `Claude Code: ${detail}` });
+                }
+            }
+        }
+        if (signal.aborted)
+            throw new Error("aborted");
+    }
+}

package/dist/src/engines/codex.js

@@ -0,0 +1,131 @@
+import { execFileSync } from "child_process";
+import { statSync } from "fs";
+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;
+/** 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;
+    try {
+        files = execFileSync("git", ["ls-files", "-co", "--exclude-standard"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] })
+            .split("\n").filter(Boolean).slice(0, MAX_FILES);
+    }
+    catch {
+        files = listAllFiles(MAX_FILES);
+    }
+    return files.filter((file) => {
+        try {
+            return statSync(file).size <= MAX_BYTES;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Codex's errors, with what to do about the common one: not being signed in. */
+function explain(message) {
+    const first = message.split("\n")[0];
+    if (/401|Unauthorized|authentication|not logged in/i.test(message)) {
+        return "Codex isn't signed in. Run `codex login` (or set OPENAI_API_KEY), then try again.";
+    }
+    return first;
+}
+/**
+ * Codex through the Codex SDK. Codex has no per-edit approval hook: it works in its workspace sandbox, and
+ * Nou keeps a copy of the project's files at the start of each message so every change it made can be
+ * shown and undone afterwards.
+ */
+export class CodexEngine extends ExternalEngine {
+    id = "codex";
+    thread = null;
+    introduced = false;
+    constructor(choice, hooks) {
+        super(choice, hooks, "Codex");
+    }
+    resetConversation() {
+        this.thread = null;
+        this.introduced = false;
+    }
+    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({
+            workingDirectory: process.cwd(),
+            skipGitRepoCheck: true,
+            sandboxMode: "workspace-write",
+            approvalPolicy: "never",
+            ...(this.choice.provider.id === "openai" ? { model: this.choice.model } : {}),
+            ...(this.effort && EFFORTS.has(this.effort) ? { modelReasoningEffort: this.effort } : {}),
+        });
+        // 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());
+        let failure;
+        try {
+            const { events } = await this.thread.runStreamed(input, { signal });
+            for await (const event of events)
+                failure = (await this.handle(event)) ?? failure;
+        }
+        catch (error) {
+            // The codex process exiting with an error ends the stream; its first line says why.
+            if (signal.aborted)
+                throw error;
+            failure ??= error.message;
+        }
+        if (signal.aborted)
+            throw new Error("aborted");
+        if (failure)
+            throw new Error(explain(failure));
+    }
+    /** Shows one Codex event; returns the error message if the turn failed. */
+    async handle(event) {
+        if (event.type === "item.updated" && event.item.type === "agent_message") {
+            this.hooks.onStream(event.item.text);
+        }
+        else if (event.type === "item.started" && event.item.type === "command_execution") {
+            this.hooks.onBusy(`Codex: ${event.item.command}`);
+        }
+        else if (event.type === "item.completed") {
+            const item = event.item;
+            if (item.type === "agent_message") {
+                this.hooks.onStream("");
+                if (item.text.trim())
+                    this.hooks.onEntry({ kind: "assistant", text: item.text.trim() });
+            }
+            else if (item.type === "command_execution") {
+                this.hooks.onEntry({ kind: "tool", text: `Ran: ${item.command}${item.exit_code ? ` (exit ${item.exit_code})` : ""}` });
+                this.hooks.onBusy("Codex is working...");
+            }
+            else if (item.type === "file_change") {
+                for (const change of item.changes) {
+                    if (change.kind === "delete")
+                        this.hooks.onEntry({ kind: "tool", text: `Deleted ${change.path}` });
+                    else
+                        await this.tracker.applied(change.path, change.kind === "add");
+                }
+            }
+            else if (item.type === "web_search") {
+                this.hooks.onEntry({ kind: "tool", text: `Searched the web: ${item.query}` });
+            }
+            else if (item.type === "mcp_tool_call") {
+                this.hooks.onEntry({ kind: "tool", text: `${item.server}: ${item.tool}` });
+            }
+            else if (item.type === "error") {
+                // Warnings and retries ("Reconnecting... 2/5") show as progress, not as a stack of errors.
+                this.hooks.onBusy(`Codex: ${item.message.slice(0, 100)}`);
+            }
+        }
+        else if (event.type === "turn.failed") {
+            return event.error.message;
+        }
+        else if (event.type === "error") {
+            return event.message;
+        }
+        return undefined;
+    }
+}

package/dist/src/engines/external.js

@@ -0,0 +1,152 @@
+import { readFileSync } from "fs";
+import path from "path";
+import { newSessionId } from "../agent/index.js";
+import { isInProject, toRelative } from "../commands/index.js";
+function readOrNull(filePath) {
+    try {
+        return readFileSync(path.resolve(process.cwd(), filePath), "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Replaces `oldText` with `newText`, as edit tools do; null if it isn't there (the tool will fail on its own). */
+export function replaceIn(text, oldText, newText, all = false) {
+    if (!oldText || !text.includes(oldText))
+        return null;
+    return all ? text.split(oldText).join(newText) : text.replace(oldText, () => newText);
+}
+/**
+ * Lets an engine that edits files itself still go through Nou: approve() shows the proposed diff (or asks,
+ * when the engine's edit can't be previewed) and remembers the file as it was; applied() reads what the
+ * engine actually wrote, records it for undo and returns any problems it introduced.
+ */
+export class ChangeTracker {
+    hooks;
+    turnId;
+    before = new Map();
+    constructor(hooks, turnId) {
+        this.hooks = hooks;
+        this.turnId = turnId;
+    }
+    /** `after` is the file's proposed new content, or undefined when it can't be worked out in advance. */
+    async approve(filePath, after, tool) {
+        const rel = toRelative(filePath);
+        if (!isInProject(filePath))
+            return this.hooks.approve({ kind: "tool", name: tool, args: { path: filePath } });
+        const before = readOrNull(rel);
+        if (after === undefined) {
+            const ok = await this.hooks.approve({ kind: "tool", name: tool, args: { path: rel } });
+            if (ok)
+                this.before.set(rel, before);
+            return ok;
+        }
+        const change = { path: rel, before: before ?? "", after, isNew: before === null };
+        this.hooks.onChange(change, "pending", this.turnId());
+        const ok = await this.hooks.approve({ kind: "change", change });
+        if (ok)
+            this.before.set(rel, before);
+        else {
+            this.hooks.onChange(change, "rejected", this.turnId());
+            this.hooks.onEntry({ kind: "tool", text: `Rejected edit to ${rel}` });
+        }
+        return ok;
+    }
+    /** For engines that edit without asking: remember files as they are now, so changes can be shown and undone. */
+    remember(files) {
+        for (const file of files) {
+            const rel = toRelative(file);
+            if (!this.before.has(rel))
+                this.before.set(rel, readOrNull(rel));
+        }
+    }
+    /**
+     * After the engine wrote the file: records the change and returns problems it introduced, if any.
+     * `created` marks a file the engine says it added, which won't have been remembered beforehand.
+     */
+    async applied(filePath, created = false) {
+        const rel = toRelative(filePath);
+        if (!this.before.has(rel) && !created)
+            return null;
+        const before = this.before.get(rel) ?? null;
+        this.before.delete(rel);
+        const after = readOrNull(rel);
+        if (after === null || after === before)
+            return null;
+        const change = { path: rel, before: before ?? "", after, isNew: before === null };
+        this.hooks.onChange(change, "applied", this.turnId());
+        this.hooks.onEntry({ kind: "tool", text: `${change.isNew ? "Created" : "Edited"} ${rel}` });
+        const problems = await this.hooks.checkChange?.(change).catch(() => null);
+        if (problems)
+            this.hooks.onEntry({ kind: "error", text: `New problems in ${rel}:\n${problems}` });
+        return problems ?? null;
+    }
+    clear() {
+        this.before.clear();
+    }
+}
+/** What engines that run their own agent loop share: turn bookkeeping, notes, cancelling and error reporting. */
+export class ExternalEngine {
+    choice;
+    hooks;
+    label;
+    turn = 0;
+    session = newSessionId();
+    extras = [];
+    effort;
+    notes = [];
+    controller = null;
+    tracker;
+    constructor(choice, hooks, label) {
+        this.choice = choice;
+        this.hooks = hooks;
+        this.label = label;
+        this.tracker = new ChangeTracker(hooks, () => this.turnId);
+    }
+    get turnId() {
+        return `${this.session}:${this.turn}`;
+    }
+    configure(options) {
+        if (options.extras)
+            this.extras = options.extras;
+        if (options.effort)
+            this.effort = options.effort;
+    }
+    setModel(choice) {
+        this.choice = choice;
+        this.resetConversation();
+    }
+    clear() {
+        this.notes = [];
+        this.resetConversation();
+    }
+    note(text) {
+        this.notes.push(text);
+    }
+    cancel() {
+        this.controller?.abort();
+    }
+    async send(text, context) {
+        this.turn++;
+        const notes = this.notes.length ? `${this.notes.map((n) => `[Note: ${n}]`).join("\n")}\n\n` : "";
+        this.notes = [];
+        this.controller = new AbortController();
+        const { signal } = this.controller;
+        this.hooks.onBusy(`Working with ${this.label}...`);
+        try {
+            await this.run(`${notes}${text}${context ? `\n\n${context}` : ""}`, signal);
+        }
+        catch (error) {
+            if (signal.aborted)
+                this.hooks.onEntry({ kind: "info", text: "Cancelled." });
+            else
+                this.hooks.onEntry({ kind: "error", text: `${this.label}: ${error.message}` });
+        }
+        finally {
+            this.hooks.onStream("");
+            this.tracker.clear();
+            this.controller = null;
+            this.hooks.onBusy(null);
+        }
+    }
+}

package/dist/src/engines/index.js

@@ -0,0 +1,127 @@
+import { spawn } from "child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+import { Agent } from "../agent/index.js";
+import { NOU_HOME } from "../config/index.js";
+import { ClaudeCodeEngine } from "./claude.js";
+import { CodexEngine } from "./codex.js";
+import { PiEngine } from "./pi.js";
+import { ENGINE_IDS } from "./types.js";
+export * from "./types.js";
+/** Where optional engines are installed (`npm install --prefix`), so Nou itself stays small. */
+export const ENGINE_DIR = process.env.NOU_ENGINE_DIR || path.join(NOU_HOME, "engines");
+export const ENGINES = [
+    {
+        id: "nou",
+        label: "Nou",
+        description: "Nou's own agent. Works with every model, local or cloud.",
+        approvals: "before",
+        model: (choice) => `${choice.provider.id}:${choice.model}`,
+    },
+    {
+        id: "claude-code",
+        label: "Claude Code",
+        description: "Anthropic's agent (Claude Agent SDK). Claude models; uses your API key or Claude login.",
+        package: "@anthropic-ai/claude-agent-sdk",
+        approvals: "before",
+        model: (choice) => (choice.provider.id === "anthropic" ? choice.model : "Claude Code's default model"),
+    },
+    {
+        id: "codex",
+        label: "Codex",
+        description: "OpenAI's agent (Codex SDK). OpenAI models; uses your API key or ChatGPT login. Edits in a sandbox without asking; review and undo after.",
+        package: "@openai/codex-sdk",
+        approvals: "after",
+        model: (choice) => (choice.provider.id === "openai" ? choice.model : "Codex's default model"),
+    },
+    {
+        id: "pi",
+        label: "pi",
+        description: "The minimal pi coding agent. Works with your Nou model, local or cloud.",
+        package: "@earendil-works/pi-coding-agent",
+        approvals: "before",
+        model: (choice) => `${choice.provider.id}:${choice.model}`,
+    },
+];
+export const engineInfo = (id) => ENGINES.find((e) => e.id === id);
+export const isEngineId = (id) => ENGINE_IDS.includes(id);
+/** Where a package's ESM entry point is, under `node_modules` of `base`, or null if it isn't installed there. */
+function entryPoint(base, pkg) {
+    const dir = path.join(base, "node_modules", ...pkg.split("/"));
+    const manifest = path.join(dir, "package.json");
+    if (!existsSync(manifest))
+        return null;
+    const json = JSON.parse(readFileSync(manifest, "utf-8"));
+    let entry = json.exports?.["."] ?? json.exports ?? json.module ?? json.main ?? "index.js";
+    // Conditional exports: prefer import, then default (some nest them, e.g. { import: { default } }).
+    while (entry && typeof entry === "object")
+        entry = entry.import ?? entry.default ?? entry.node;
+    return typeof entry === "string" ? path.join(dir, entry) : null;
+}
+/** Nou's own package folder (for engines installed as ordinary dependencies, e.g. in development). */
+function ownDir() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 5 && !existsSync(path.join(dir, "package.json")); i++)
+        dir = path.dirname(dir);
+    return dir;
+}
+function findPackage(pkg) {
+    return entryPoint(ENGINE_DIR, pkg) ?? entryPoint(ownDir(), pkg);
+}
+export const isInstalled = (info) => !info.package || findPackage(info.package) !== null;
+/** Imports an engine's package; it must be installed (see installEngine). */
+export async function loadPackage(pkg) {
+    const entry = findPackage(pkg);
+    if (!entry)
+        throw new Error(`${pkg} isn't installed. Pick the engine again in /settings to install it.`);
+    return import(pathToFileURL(entry).href);
+}
+/** Installs an engine's package into ~/.nou/engines. `onLine` gets npm's output as it goes. */
+export function installEngine(info, onLine, signal) {
+    if (!info.package)
+        return Promise.resolve();
+    mkdirSync(ENGINE_DIR, { recursive: true });
+    const manifest = path.join(ENGINE_DIR, "package.json");
+    if (!existsSync(manifest))
+        writeFileSync(manifest, JSON.stringify({ name: "nou-engines", private: true }, null, 2));
+    return new Promise((resolve, reject) => {
+        const child = spawn("npm", ["install", "--prefix", ENGINE_DIR, "--no-audit", "--no-fund", info.package], { shell: process.platform === "win32" });
+        const onAbort = () => child.kill();
+        signal?.addEventListener("abort", onAbort);
+        let tail = "";
+        const read = (data) => {
+            for (const line of data.toString().split(/\r?\n/)) {
+                if (!line.trim())
+                    continue;
+                tail = line;
+                onLine(line.trim());
+            }
+        };
+        child.stdout.on("data", read);
+        child.stderr.on("data", read);
+        child.on("error", reject);
+        child.on("close", (code) => {
+            signal?.removeEventListener("abort", onAbort);
+            if (signal?.aborted)
+                reject(new Error("stopped"));
+            else if (code === 0)
+                resolve();
+            else
+                reject(new Error(`npm install failed (exit ${code}): ${tail}`));
+        });
+    });
+}
+/** Creates the engine; external ones load their package when they first run. */
+export function createEngine(id, choice, system, hooks) {
+    switch (id) {
+        case "claude-code":
+            return new ClaudeCodeEngine(choice, hooks);
+        case "codex":
+            return new CodexEngine(choice, hooks);
+        case "pi":
+            return new PiEngine(choice, hooks);
+        default:
+            return new Agent(choice, system, hooks);
+    }
+}