@xingjisoft/neutrino 0.1.7 → 0.2.0

package/dist/config.js

@@ -56,6 +56,9 @@ export const DEFAULT_CONFIG = {
     language: "en",
     theme: "default",
     default_intensity: "High",
+    // Plan a request into steps before answering it: the planner agent writes the
+    // plan, the worker executes one step per turn. Off = answer in one pass.
+    plan_first: true,
     // Default for new conversations; each conversation can override it.
     approval_mode: "request",
     // Delete-class commands need a human unless this and Auto Approval are on.
@@ -64,6 +67,9 @@ export const DEFAULT_CONFIG = {
     sound_alerts: true,
     // Model that reviews approval requests. Empty = same model as the chat.
     approval_model: "",
+    // Mount the browser UI alongside the terminal UI unless it is turned off
+    // here or on the command line.
+    web_console: true,
     // Initialized as a salted hash of the default Web password on first use.
     web_password_hash: "",
 };
@@ -163,7 +169,7 @@ export function resolveModelSelection(value, requireKey = true) {
         throw new Error("this model has no API key configured");
     return { provider: provider.name, model: { ...model }, intensity: input.intensity };
 }
-export function saveSession(messages, modelName, provider, intensity, cwd, sessionId, tokens, context, approvalMode) {
+export function saveSession(messages, modelName, provider, intensity, cwd, sessionId, tokens, context, approvalMode, plan) {
     ensureDirs();
     const now = new Date();
     const id = sessionId ?? `${now.toISOString().replace(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}`;
@@ -192,6 +198,10 @@ export function saveSession(messages, modelName, provider, intensity, cwd, sessi
     const validContext = normalizeContext(context, messages.filter((m) => m.role !== "system").length);
     if (validContext)
         session.context = validContext;
+    // A plan outlives the turn that produced it: reopening a conversation shows
+    // how far it got, and a stopped plan is still the record of what was agreed.
+    if (plan && plan.steps.length)
+        session.plan = plan;
     const filePath = path.join(SESSION_DIR, `${id}.json`);
     // Keep the last complete transcript intact if writing or replacing fails.
     // The temporary file shares the destination directory so rename is atomic.
@@ -302,6 +312,40 @@ export function loadPrompt() {
     return (readAsset(path.join(PKG_ROOT, "assets", "prompt.txt"), path.join(PKG_ROOT, "prompt.txt")) ??
         "You are Neutrino, a helpful AI coding assistant.");
 }
+/** The planning agent's system prompt. */
+export function loadPlannerPrompt() {
+    return (readAsset(path.join(PKG_ROOT, "assets", "planner.txt"), path.join(PKG_ROOT, "planner.txt")) ??
+        "Split the user's request into ordered, independent steps a coding agent can execute one at a " +
+            "time. Answer with JSON only: {\"goal\": \"...\", \"steps\": [{\"title\": \"...\"}]}.");
+}
+/** Template for the per-step system text; `{{index}}`, `{{plan}}`, … are filled in. */
+export function loadStepPrompt() {
+    return (readAsset(path.join(PKG_ROOT, "assets", "step.txt"), path.join(PKG_ROOT, "step.txt")) ??
+        "You are executing step {{index}} of {{total}} of this plan:\n{{plan}}\n\nDo only: {{step}}\n" +
+            "Verify it, then stop and report what you did.");
+}
+/** The system prompt a delegated sub-agent works from. */
+export function loadSubAgentPrompt() {
+    return (readAsset(path.join(PKG_ROOT, "assets", "subagent.txt"), path.join(PKG_ROOT, "subagent.txt")) ??
+        "You are a sub-agent working on one task delegated by another agent. You cannot ask the user " +
+            "anything and you cannot delegate further. Do the task with the tools you have, verify it, and " +
+            "report what you did and what you found in your final message.");
+}
+/**
+ * Whether a turn is planned before it is executed. Unset means on: the plan is
+ * the default workflow, and only an explicit `false` turns it off.
+ *
+ * `NEUTRINO_PLAN=off` overrides both ways for a single run, the way the other
+ * environment variables override the saved configuration.
+ */
+export function planFirstEnabled() {
+    const override = String(process.env.NEUTRINO_PLAN ?? "").trim().toLowerCase();
+    if (override === "off" || override === "0" || override === "false" || override === "no")
+        return false;
+    if (override === "on" || override === "1" || override === "true" || override === "yes")
+        return true;
+    return loadConfig().plan_first !== false;
+}
 let cachedVersion = null;
 /**
  * Read the CLI version straight from the package's `package.json` so the

package/dist/header.js

@@ -23,6 +23,11 @@ export function drawHeader(buf, state) {
     }
     buf.fillRect(0, 0, w, 1, { bg: C.highlightBg });
     let text = `${state.selectedProvider}/${state.selectedModelName} | ${state.selectedIntensity}`;
+    if (state.webUrl) {
+        // A short reminder that the browser console is live; the startup message
+        // prints the full addresses when more than one works.
+        text += `  ·  web ${state.webUrl.replace(/^https?:\/\//, "").replace(/\/$/, "")}`;
+    }
     text = truncateByWidth(text, w);
     buf.centerText(0, text, { fg: C.accent, bg: C.highlightBg, bold: true });
 }

package/dist/llm/client.js

@@ -1,6 +1,9 @@
 import { INTENSITY_PARAMS } from "../config.js";
-/** How many extra times a request is retried when the connection drops. */
-const NETWORK_RETRIES = 2;
+import { HttpStatusError, describeError, isRetriableFailure, retryDelayMs, retryPolicy, waitBeforeRetry, } from "./retry.js";
+// Callers import `describeError` from this module; it lives next to the
+// classification helpers that share the same "is this a dropped connection?"
+// knowledge, so it is re-exported rather than duplicated.
+export { describeError } from "./retry.js";
 /** Give up if the server has not started to respond within this window. */
 const CONNECT_TIMEOUT_MS = 120_000;
 /**
@@ -14,124 +17,34 @@ const SUMMARY_SYSTEM_PROMPT = "You compress the conversation history of an AI co
     "and their meaningful results, and any unresolved problems or next steps. Drop pleasantries, restated " +
     "instructions and redundant tool output. Output only the summary, with no preface.";
 /**
- * Terse transport messages that all mean "the connection dropped mid-flight".
- * The \b keeps "terminated" from matching unrelated text such as
- * "Unterminated string constant".
- */
-const DROP_HINT_RE = /\bterminated\b|other side closed|socket hang up|premature close/i;
-/**
- * Flatten an error and its `cause` chain into one readable line.
+ * One POST, bounded by a connect timeout.
  *
- * `fetch` reports almost every transport problem as a bare
- * `TypeError: fetch failed`; the actual reason (`ECONNRESET`, `EMFILE`,
- * `ENOTFOUND`, `UND_ERR_…`) is tucked away in `error.cause`. Without walking
- * that chain a failure is impossible to diagnose, so this always reports it.
+ * Retrying deliberately does *not* happen here: only the caller knows whether a
+ * token already reached the user, and nesting two retry loops would multiply
+ * both the request count and the total wait by the attempt budget.
  */
-export function describeError(e) {
-    if (!(e instanceof Error))
-        return String(e);
-    const parts = [];
-    const push = (msg, code) => {
-        const text = code && !msg.includes(code) ? `${msg} (${code})` : msg;
-        if (text && !parts.includes(text))
-            parts.push(text);
-    };
-    let cur = e;
-    const seen = new Set();
-    while (cur != null && !seen.has(cur)) {
-        if (typeof cur === "string") {
-            // fetch/undici sometimes stash the real reason in a plain string
-            // (`cause: "other side closed"`), which an object-only walk would miss.
-            push(cur);
-            break;
-        }
-        if (typeof cur !== "object")
-            break;
-        seen.add(cur);
-        const err = cur;
-        const message = typeof err.message === "string" && err.message ? err.message : String(err.name ?? "Error");
-        const code = typeof err.code === "string" ? err.code : undefined;
-        push(message, code);
-        cur = err.cause;
+async function postStream(url, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`request timed out after ${CONNECT_TIMEOUT_MS / 1000}s`)), CONNECT_TIMEOUT_MS);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
     }
-    const text = parts.join(": ") || e.message;
-    // A dropped mid-stream connection surfaces as a bare `TypeError: terminated`,
-    // which on its own tells the user nothing worth reading.
-    return DROP_HINT_RE.test(text) ? `${text} — the connection was closed before the response finished` : text;
-}
-/**
- * Whether a failed request is worth retrying: a transient connection problem
- * (reset / refused / DNS / timeout) rather than a real response from the API.
- */
-function isRetriableNetworkError(e) {
-    const transient = new Set([
-        "ECONNRESET",
-        "ECONNREFUSED",
-        "ECONNABORTED",
-        "EPIPE",
-        "ETIMEDOUT",
-        "ENETUNREACH",
-        "ENETDOWN",
-        "EAI_AGAIN",
-        "ERR_STREAM_PREMATURE_CLOSE",
-        "UND_ERR_SOCKET",
-        "UND_ERR_CONNECT_TIMEOUT",
-    ]);
-    let cur = e;
-    const seen = new Set();
-    while (cur != null && !seen.has(cur)) {
-        if (typeof cur === "string") {
-            if (DROP_HINT_RE.test(cur))
-                return true;
-            break;
-        }
-        if (typeof cur !== "object")
-            break;
-        seen.add(cur);
-        const err = cur;
-        if (typeof err.code === "string" && transient.has(err.code))
-            return true;
-        // Our own connect timeout aborts with a plain AbortError; undici wraps a
-        // dropped socket in a SocketError.
-        if (err.name === "AbortError" || err.name === "SocketError")
-            return true;
-        // A stream that dies mid-flight: "terminated", "socket hang up", …
-        if (typeof err.message === "string" && DROP_HINT_RE.test(err.message))
-            return true;
-        cur = err.cause;
+    finally {
+        clearTimeout(timer);
     }
-    // Undici's generic wrapper: assume the socket dropped and try again.
-    return e instanceof Error && /fetch failed/i.test(e.message);
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+/** The policy a stream will actually use, with any per-call override applied. */
+function resolvePolicy(options) {
+    return { ...retryPolicy(), ...options.retry };
 }
 /**
- * Issue a streaming request, retrying a few times on transient network errors
- * and giving up with a clear error if the server never starts responding.
- *
- * Retries are safe here because they only ever happen *before* a response is
- * returned; once bytes start flowing the caller is responsible for the stream.
+ * Wait before the next attempt, telling the caller why the stream went quiet.
+ * Returns false when the caller stopped caring during the wait.
  */
-async function requestStream(url, init) {
-    let lastErr;
-    for (let attempt = 0; attempt <= NETWORK_RETRIES; attempt++) {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(new Error(`request timed out after ${CONNECT_TIMEOUT_MS / 1000}s`)), CONNECT_TIMEOUT_MS);
-        try {
-            const resp = await fetch(url, { ...init, signal: controller.signal });
-            clearTimeout(timer);
-            return resp;
-        }
-        catch (e) {
-            clearTimeout(timer);
-            lastErr = e;
-            if (attempt === NETWORK_RETRIES || !isRetriableNetworkError(e))
-                throw e;
-            await sleep(300 * (attempt + 1));
-        }
-    }
-    throw lastErr;
+async function pauseForRetry(attempt, policy, error, options) {
+    const delayMs = retryDelayMs(attempt - 1, policy);
+    options.onRetry?.({ attempt: attempt + 1, attempts: policy.attempts, delayMs, reason: describeError(error) });
+    return waitBeforeRetry(attempt - 1, policy, options.cancelled);
 }
 export class LLMClient {
     model;
@@ -155,13 +68,13 @@ export class LLMClient {
      * the old messages. Uses a throw-away request (no tools) via the normal
      * streaming path, so provider differences are handled for free.
      */
-    async summarize(transcript) {
+    async summarize(transcript, options = {}) {
         const messages = [
             { role: "system", content: SUMMARY_SYSTEM_PROMPT },
             { role: "user", content: transcript },
         ];
         let out = "";
-        for await (const chunk of this.streamTurn(messages))
+        for await (const chunk of this.streamTurn(messages, undefined, options))
             out += chunk;
         const text = out.trim();
         if (!text || text.startsWith("[Error"))
@@ -172,41 +85,45 @@ export class LLMClient {
      * One-shot completion with its own system prompt. The approval reviewers use
      * this so they never share context with the conversation they are judging.
      */
-    async complete(system, user) {
+    async complete(system, user, options = {}) {
         let out = "";
         for await (const chunk of this.streamTurn([
             { role: "system", content: system },
             { role: "user", content: user },
-        ])) {
+        ], undefined, options)) {
             out += chunk;
         }
         return out.trim();
     }
-    async *streamTurn(messages, tools) {
+    async *streamTurn(messages, tools, options = {}) {
         this.toolCalls = [];
         this.usage = null;
         try {
             if (this.provider === "Anthropic") {
-                yield* this.streamAnthropic(messages);
+                yield* this.streamAnthropic(messages, options);
                 return;
             }
-            yield* this.streamOpenAI(messages, tools);
+            yield* this.streamOpenAI(messages, tools, options);
         }
         catch (e) {
             yield `\n[Error: ${describeError(e)}]`;
         }
     }
     /**
-     * Drive one request, retrying if the stream dies before it produced anything.
+     * Drive one request, retrying while the failure is transient.
      *
      * A response can be cut off on the very first read — "terminated" when a
-     * proxy or the server closes the connection mid-flight. Nothing has reached
-     * the user yet, so re-issuing the request is invisible (and cannot duplicate
-     * text). Once a token has been emitted a retry is unsafe, so the error is
-     * surfaced instead.
+     * proxy or the server closes the connection mid-flight — or the request can
+     * never leave at all. Nothing has reached the user yet, so re-issuing is
+     * invisible and cannot duplicate text; the attempts and the 5s/10s/20s/…
+     * backoff live in `retry.ts`.
+     *
+     * Once a token has been emitted a retry would replay the reply from its
+     * beginning, so the error is surfaced instead and the partial text is kept.
      */
-    async *streamOpenAI(messages, tools) {
-        for (let attempt = 0;; attempt++) {
+    async *streamOpenAI(messages, tools, options) {
+        const policy = resolvePolicy(options);
+        for (let attempt = 1;; attempt++) {
             this.toolCalls = [];
             let produced = false;
             try {
@@ -217,9 +134,10 @@ export class LLMClient {
                 return;
             }
             catch (e) {
-                if (produced || attempt >= NETWORK_RETRIES || !isRetriableNetworkError(e))
+                if (produced || attempt >= policy.attempts || !isRetriableFailure(e))
                     throw e;
-                await sleep(400 * (attempt + 1));
+                if (!(await pauseForRetry(attempt, policy, e, options)))
+                    return;
             }
         }
     }
@@ -240,15 +158,17 @@ export class LLMClient {
         };
         if (tools && tools.length)
             payload.tools = tools;
-        const resp = await requestStream(url, {
+        const resp = await postStream(url, {
             method: "POST",
             headers,
             body: JSON.stringify(payload),
         });
         if (!resp.ok) {
-            const text = await resp.text().catch(() => "");
-            yield `\n[Error: HTTP ${resp.status}${text ? " - " + text.slice(0, 500) : ""}]`;
-            return;
+            // Thrown rather than printed: a 502/503/504/429 is as transient as a
+            // reset and deserves the same retries, while a 400/401 must surface at
+            // once. `streamTurn` renders the final failure into the transcript.
+            const body = await resp.text().catch(() => "");
+            throw new HttpStatusError(resp.status, body.slice(0, 500));
         }
         if (!resp.body) {
             yield "\n[Error: empty response body]";
@@ -333,8 +253,9 @@ export class LLMClient {
             .map((k) => toolCallsByIndex[k]);
     }
     /** Anthropic counterpart of `streamOpenAI`, with the same retry policy. */
-    async *streamAnthropic(messages) {
-        for (let attempt = 0;; attempt++) {
+    async *streamAnthropic(messages, options) {
+        const policy = resolvePolicy(options);
+        for (let attempt = 1;; attempt++) {
             this.toolCalls = [];
             let produced = false;
             try {
@@ -345,9 +266,10 @@ export class LLMClient {
                 return;
             }
             catch (e) {
-                if (produced || attempt >= NETWORK_RETRIES || !isRetriableNetworkError(e))
+                if (produced || attempt >= policy.attempts || !isRetriableFailure(e))
                     throw e;
-                await sleep(400 * (attempt + 1));
+                if (!(await pauseForRetry(attempt, policy, e, options)))
+                    return;
             }
         }
     }
@@ -376,15 +298,17 @@ export class LLMClient {
         };
         if (systemMsg)
             payload.system = systemMsg;
-        const resp = await requestStream(url, {
+        const resp = await postStream(url, {
             method: "POST",
             headers,
             body: JSON.stringify(payload),
         });
         if (!resp.ok) {
-            const text = await resp.text().catch(() => "");
-            yield `\n[Error: HTTP ${resp.status}${text ? " - " + text.slice(0, 500) : ""}]`;
-            return;
+            // Thrown rather than printed: a 502/503/504/429 is as transient as a
+            // reset and deserves the same retries, while a 400/401 must surface at
+            // once. `streamTurn` renders the final failure into the transcript.
+            const body = await resp.text().catch(() => "");
+            throw new HttpStatusError(resp.status, body.slice(0, 500));
         }
         if (!resp.body) {
             yield "\n[Error: empty response body]";