@xingjisoft/neutrino 0.1.6 → 0.2.0

package/dist/llm/plan.js

@@ -0,0 +1,403 @@
+/**
+ * Plan-first turns.
+ *
+ * A request is answered in two passes. A *planner* agent turns the user's text
+ * into an ordered list of independent steps; a *worker* agent is then handed one
+ * step at a time and never sees the rest of the plan as work it may start. That
+ * split is what makes the later work explicit: every step names one deliverable,
+ * so it can be executed, verified and shown on its own.
+ *
+ * This module is deliberately free of I/O: it parses the planner's answer, turns
+ * the plan into prompt text, and lays the plan out as the rows of the info card.
+ * The model calls themselves live in the two agent loops.
+ */
+import { displayWidth, ellipsize } from "../width.js";
+/**
+ * One step is not a plan, it is the answer: such a turn runs as a plain turn.
+ * The ceiling keeps the card readable and the turn's cost proportionate.
+ */
+export const PLAN_MIN_STEPS = 2;
+export const PLAN_MAX_STEPS = 10;
+export const PLAN_MAX_TITLE = 160;
+export const PLAN_MAX_DETAIL = 400;
+// ------------------------------------------------------------------ parsing
+function cleanText(value, max) {
+    if (typeof value !== "string")
+        return "";
+    return value.replace(/\s+/g, " ").trim().slice(0, max);
+}
+function normalizeStep(value) {
+    if (typeof value === "string") {
+        const title = cleanText(value, PLAN_MAX_TITLE);
+        return title ? { title, status: "pending" } : null;
+    }
+    if (!value || typeof value !== "object")
+        return null;
+    const o = value;
+    // Models name the same field differently; accept the common spellings rather
+    // than rejecting a plan over a key name.
+    const title = cleanText(o.title ?? o.step ?? o.task ?? o.action, PLAN_MAX_TITLE);
+    if (!title)
+        return null;
+    const detail = cleanText(o.detail ?? o.description ?? o.how ?? o.acceptance, PLAN_MAX_DETAIL);
+    return { title, status: "pending", ...(detail ? { detail } : {}) };
+}
+/** Turn an already-parsed planner answer into a plan, or null when unusable. */
+export function normalizePlan(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const o = value;
+    const rawSteps = Array.isArray(value) ? value : Array.isArray(o.steps) ? o.steps : Array.isArray(o.plan) ? o.plan : null;
+    if (!rawSteps)
+        return null;
+    const steps = [];
+    for (const item of rawSteps) {
+        const step = normalizeStep(item);
+        if (step)
+            steps.push(step);
+        if (steps.length >= PLAN_MAX_STEPS)
+            break;
+    }
+    if (steps.length < PLAN_MIN_STEPS)
+        return null;
+    const goal = cleanText(o.goal ?? o.title ?? o.summary ?? o.request, 240);
+    return { goal, steps };
+}
+/**
+ * Every top-level `{…}` block in the text, in order.
+ *
+ * A planner is asked for bare JSON but models still wrap it in a fence or add a
+ * sentence before it; scanning for a balanced object finds it without guessing
+ * where the JSON starts and stops. Strings and escapes are tracked so a brace
+ * inside a step title cannot end the scan early.
+ */
+function jsonCandidates(text) {
+    const out = [];
+    let depth = 0;
+    let start = -1;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === "\\")
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"')
+            inString = true;
+        else if (ch === "{") {
+            if (depth === 0)
+                start = i;
+            depth++;
+        }
+        else if (ch === "}") {
+            depth--;
+            if (depth === 0 && start >= 0) {
+                out.push(text.slice(start, i + 1));
+                start = -1;
+            }
+            if (depth < 0)
+                depth = 0;
+        }
+    }
+    return out;
+}
+/** A numbered or bulleted list, for a planner that answered in prose. */
+function planFromList(text) {
+    const steps = [];
+    for (const line of text.split("\n")) {
+        // "1." "1)" "1、" and bullets all show up in practice, with or without a
+        // space after the marker.
+        const match = /^\s*(?:\d+\s*[.):、]\s*|[-*•]\s+)(.+)$/.exec(line);
+        if (!match)
+            continue;
+        const title = cleanText(match[1], PLAN_MAX_TITLE);
+        if (!title)
+            continue;
+        steps.push({ title, status: "pending" });
+        if (steps.length >= PLAN_MAX_STEPS)
+            break;
+    }
+    if (steps.length < PLAN_MIN_STEPS)
+        return null;
+    return { goal: "", steps };
+}
+/**
+ * Read a planner answer. JSON first, because that is what the prompt asks for,
+ * then a numbered list so a model that ignores the format still produces a
+ * usable plan. Anything else is "no plan": the turn then runs as before.
+ */
+export function parsePlan(text) {
+    const raw = String(text ?? "").trim();
+    if (!raw || /^\[Error/.test(raw))
+        return null;
+    for (const candidate of jsonCandidates(raw)) {
+        let value;
+        try {
+            value = JSON.parse(candidate);
+        }
+        catch {
+            continue;
+        }
+        const plan = normalizePlan(value);
+        if (plan)
+            return plan;
+    }
+    return planFromList(raw);
+}
+/**
+ * The user turn handed to the planner agent. The planner gets no tools, so
+ * everything it needs to make the steps concrete is in this text: where the
+ * work happens, what was said before, and what is being asked now.
+ */
+export function buildPlannerInput(input) {
+    const parts = [];
+    if (input.cwd)
+        parts.push(`Working directory: ${input.cwd}`);
+    const transcript = (input.transcript ?? "").trim();
+    if (transcript)
+        parts.push(`Conversation so far (oldest first):\n${transcript}`);
+    parts.push(`Current request:\n${input.request.trim()}`);
+    return parts.join("\n\n");
+}
+/** The plan as numbered text: what the worker and the reviewers read. */
+export function planSpec(plan) {
+    return plan.steps
+        .map((step, i) => `${i + 1}. ${step.title}${step.detail ? `\n   detail: ${step.detail}` : ""}`)
+        .join("\n");
+}
+/**
+ * The plan as the user reads it in the transcript. It is an ordinary assistant
+ * message on purpose: it is saved, replayed, folded and sent back to the model
+ * exactly like any other answer.
+ *
+ * A detail stays on its step's line: markdown renderers fold an indented line
+ * into the list item before it, which would run two steps together in the log.
+ */
+export function planMessage(plan) {
+    const count = plan.steps.length;
+    const lines = [`Plan · ${count} step${count === 1 ? "" : "s"}`];
+    if (plan.goal)
+        lines.push(`> ${plan.goal}`);
+    plan.steps.forEach((step, i) => {
+        lines.push(`${i + 1}. ${step.title}${step.detail ? ` — ${step.detail}` : ""}`);
+    });
+    return lines.join("\n");
+}
+/**
+ * The system text for one step. It repeats the whole plan so the worker knows
+ * where the step sits, and states the two rules the split exists for: do only
+ * this step, and stop when it is verified.
+ */
+export function renderStepDirective(template, plan, index) {
+    const step = plan.steps[index];
+    const detail = step?.detail ? `Detail for this step: ${step.detail}` : "";
+    return template
+        .replace(/\{\{index\}\}/g, String(index + 1))
+        .replace(/\{\{total\}\}/g, String(plan.steps.length))
+        .replace(/\{\{plan\}\}/g, planSpec(plan))
+        .replace(/\{\{step\}\}/g, step?.title ?? "")
+        .replace(/\{\{detail\}\}/g, detail)
+        .trim();
+}
+/** How far a plan got. Used by the card header and by tests. */
+export function planProgress(plan) {
+    let done = 0;
+    let active = -1;
+    plan.steps.forEach((step, i) => {
+        if (step.status === "done")
+            done++;
+        if (step.status === "active" && active < 0)
+            active = i;
+    });
+    return { done, total: plan.steps.length, active };
+}
+// ------------------------------------------------------- plan bookkeeping
+//
+// Both agent loops (terminal and browser) keep the same plan state machine, so
+// the transitions live here instead of being copied into each of them.
+/** A plan loaded from disk was, by definition, no longer running. */
+export function resumePlan(loaded) {
+    if (!loaded || !Array.isArray(loaded.steps))
+        return null;
+    // Session files are hand-editable: drop entries that are not steps rather
+    // than rendering "undefined" in the card.
+    const steps = loaded.steps.filter((step) => step && typeof step.title === "string" && step.title.trim());
+    if (steps.length === 0)
+        return null;
+    loaded.steps = steps;
+    for (const step of steps) {
+        if (step.status !== "pending" && step.status !== "active" && step.status !== "done" && step.status !== "failed") {
+            step.status = "pending";
+        }
+        if (step.status === "active") {
+            // Its worker is gone: the card must not claim a step is running, and the
+            // plan is now a record of where the turn stopped.
+            step.status = "pending";
+            loaded.stopped = true;
+        }
+    }
+    return loaded;
+}
+/** Point the plan at one step. Returns false when there was nothing to change. */
+export function advancePlan(plan, index, status) {
+    const step = plan?.steps[index];
+    if (!plan || !step)
+        return false;
+    step.status = status;
+    if (status === "active")
+        plan.stopped = false;
+    return true;
+}
+/** A turn that cannot continue must not leave a step looking alive. */
+export function stopPlan(plan) {
+    if (!plan)
+        return false;
+    const active = plan.steps.find((step) => step.status === "active");
+    if (!active)
+        return false;
+    active.status = "pending";
+    plan.stopped = true;
+    return true;
+}
+/** The user message a turn answers. */
+export function lastRequestText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message.role === "user")
+            return message.content ?? "";
+    }
+    return "";
+}
+/** How many earlier messages and how much of each the planner is shown. */
+const PLANNER_TRANSCRIPT_MESSAGES = 8;
+const PLANNER_TRANSCRIPT_CHARS = 600;
+const PLANNER_TOOL_CHARS = 400;
+/**
+ * The exchanges before the current request, for the planner.
+ *
+ * Tool output is clipped hard: the planner needs to know what was done, not to
+ * re-read it, and a long log must not crowd the request out of its own plan.
+ */
+export function planTranscript(messages) {
+    let lastUser = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === "user") {
+            lastUser = i;
+            break;
+        }
+    }
+    if (lastUser < 0)
+        return "";
+    const from = Math.max(0, lastUser - PLANNER_TRANSCRIPT_MESSAGES);
+    const lines = [];
+    for (let i = from; i < lastUser; i++) {
+        const message = messages[i];
+        if (message.role === "system")
+            continue;
+        if (message.role === "tool") {
+            lines.push(`TOOL ${message.name ?? "tool"}: ${clipText(message.result ?? "", PLANNER_TOOL_CHARS)}`);
+        }
+        else if (message.role === "summary") {
+            lines.push(`SUMMARY: ${clipText(message.content ?? "", PLANNER_TOOL_CHARS)}`);
+        }
+        else {
+            lines.push(`${message.role.toUpperCase()}: ${clipText(message.content ?? "", PLANNER_TRANSCRIPT_CHARS)}`);
+        }
+    }
+    return lines.join("\n");
+}
+function clipText(text, max) {
+    const trimmed = text.trim();
+    return trimmed.length > max ? `${trimmed.slice(0, max)}…` : trimmed;
+}
+// Deliberately plain glyphs: every one of these is already used elsewhere in the
+// terminal UI, so a font that draws those lines draws the plan too.
+const STEP_GLYPH = {
+    pending: "○",
+    active: "●",
+    done: "✓",
+    failed: "✗",
+};
+/**
+ * Lay the plan out as a vertical timeline, top to bottom in execution order.
+ *
+ * A finished step is drawn dark, a step still to come is drawn lit, and the step
+ * being worked on is the one highlighted row — so the card reads as "these are
+ * done, this is running, these are next" without a legend. When the plan is
+ * longer than the room, a window around the running step is shown with the
+ * number of steps above and below it, rather than dropping the middle.
+ */
+export function planCardRows(plan, options) {
+    const width = Math.max(12, Math.floor(options.width));
+    const maxRows = Math.max(2, Math.floor(options.maxRows));
+    const steps = plan.steps;
+    const { done } = planProgress(plan);
+    const failed = steps.some((step) => step.status === "failed");
+    let header = `Plan · ${done}/${steps.length}`;
+    if (failed)
+        header += " · failed";
+    else if (done === steps.length)
+        header += " · done";
+    else if (plan.stopped)
+        header += " · stopped";
+    const rows = [{ kind: "header", text: ellipsize(header, width) }];
+    const available = maxRows - rows.length;
+    if (available <= 0)
+        return rows;
+    const focus = (() => {
+        const active = steps.findIndex((step) => step.status === "active");
+        if (active >= 0)
+            return active;
+        const firstFailed = steps.findIndex((step) => step.status === "failed");
+        if (firstFailed >= 0)
+            return firstFailed;
+        const firstPending = steps.findIndex((step) => step.status === "pending");
+        if (firstPending >= 0)
+            return firstPending;
+        return Math.max(0, steps.length - 1);
+    })();
+    // A step occupies a node row plus the connector below it, except the last
+    // visible one; the "… more" markers take a row each.
+    let span = Math.max(1, Math.min(steps.length, Math.floor((available + 1) / 2)));
+    let start = 0;
+    let end = steps.length;
+    for (;;) {
+        start = Math.max(0, Math.min(focus - Math.floor(span / 2), steps.length - span));
+        end = start + span;
+        const markers = (start > 0 ? 1 : 0) + (end < steps.length ? 1 : 0);
+        if (span * 2 - 1 + markers <= available || span <= 1)
+            break;
+        span -= 1;
+    }
+    const plural = (n) => `step${n === 1 ? "" : "s"}`;
+    if (start > 0) {
+        rows.push({ kind: "more", text: ellipsize(`… ${start} earlier ${plural(start)}`, width) });
+    }
+    for (let i = start; i < end; i++) {
+        const step = steps[i];
+        rows.push({
+            kind: `step-${step.status}`,
+            text: ellipsize(`${STEP_GLYPH[step.status]} ${i + 1}. ${step.title}`, width),
+        });
+        if (i < end - 1)
+            rows.push({ kind: "connector", text: "│" });
+    }
+    if (end < steps.length) {
+        const later = steps.length - end;
+        rows.push({ kind: "more", text: ellipsize(`… ${later} later ${plural(later)}`, width) });
+    }
+    return rows;
+}
+/** The width a card row actually needs, in columns. */
+export function planRowsWidth(rows) {
+    let width = 0;
+    for (const row of rows)
+        width = Math.max(width, displayWidth(row.text));
+    return width;
+}

package/dist/llm/retry.js

@@ -0,0 +1,209 @@
+/**
+ * Retry policy for the model connection.
+ *
+ * A single turn is minutes of work, and the connection carries it the whole way.
+ * Providers, and the proxies and load balancers in front of them, drop sockets
+ * for reasons a client can never observe: an idle timeout, a rolling restart, a
+ * middlebox resetting the flow. Those blips clear on their own within seconds,
+ * so a failed request that is simply re-sent saves the turn — while surfacing
+ * the error throws away everything the user typed and everything the model had
+ * already produced.
+ *
+ * The policy is exponential: seven attempts in total, waiting 5s, 10s, 20s,
+ * 40s, 80s and finally 160s between them (about five minutes end to end). The
+ * waits grow because a link that is merely flaky recovers long before the
+ * budget runs out, and a link that is genuinely down must not be hammered.
+ */
+/** Total tries, the first one included. */
+export const DEFAULT_NETWORK_ATTEMPTS = 7;
+/** Wait before the first retry; every further retry doubles it. */
+export const DEFAULT_RETRY_DELAY_MS = 5_000;
+/** Parse an override, ignoring anything that is not a positive integer. */
+function positiveInt(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    const value = Number(trimmed);
+    return Number.isSafeInteger(value) && value > 0 ? value : null;
+}
+/**
+ * The policy in force.
+ *
+ * Read on every use rather than cached at import time, so the environment can
+ * tune it (`NEUTRINO_NETWORK_ATTEMPTS`, `NEUTRINO_RETRY_DELAY_MS`) without a
+ * rebuild and the tests can collapse the waits to a millisecond.
+ */
+export function retryPolicy() {
+    return {
+        attempts: positiveInt(process.env.NEUTRINO_NETWORK_ATTEMPTS) ?? DEFAULT_NETWORK_ATTEMPTS,
+        baseDelayMs: positiveInt(process.env.NEUTRINO_RETRY_DELAY_MS) ?? DEFAULT_RETRY_DELAY_MS,
+    };
+}
+/** Wait before retry number `retry` (0-based): base, 2×base, 4×base, … */
+export function retryDelayMs(retry, policy = retryPolicy()) {
+    return policy.baseDelayMs * 2 ** Math.max(0, Math.floor(retry));
+}
+/** A wait in human terms: "5s", "40s", "2m 40s". */
+export function formatDelay(ms) {
+    const total = Math.max(0, Math.round(ms / 1000));
+    if (total < 60)
+        return `${total}s`;
+    const minutes = Math.floor(total / 60);
+    const seconds = total % 60;
+    return seconds ? `${minutes}m ${seconds}s` : `${minutes}m`;
+}
+/**
+ * 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_SOURCE = "\\bterminated\\b|other side closed|socket hang up|premature close";
+export const DROP_HINT_RE = new RegExp(DROP_HINT_SOURCE, "i");
+/**
+ * Superset of the hints above, used to decide whether to retry: a socket can
+ * also be reported as a bare "read ECONNRESET" with no `code` attached.
+ */
+const TRANSIENT_MESSAGE_RE = new RegExp(`${DROP_HINT_SOURCE}|connection reset|network is unreachable|connection aborted|timed out|` +
+    "\\b(?:ECONNRESET|ECONNREFUSED|ECONNABORTED|EPIPE|ETIMEDOUT|ENETUNREACH|ENETDOWN|EHOSTUNREACH|EAI_AGAIN)\\b", "i");
+/** `code` values that describe a broken socket rather than a bad request. */
+const TRANSIENT_CODES = new Set([
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "ECONNABORTED",
+    "EPIPE",
+    "ETIMEDOUT",
+    "ENETUNREACH",
+    "ENETDOWN",
+    "EHOSTUNREACH",
+    "EAI_AGAIN",
+    "ERR_STREAM_PREMATURE_CLOSE",
+    "UND_ERR_SOCKET",
+    "UND_ERR_CLOSED",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_RESPONSE_STATUS_CODE",
+]);
+/**
+ * Flatten an error and its `cause` chain into one readable line.
+ *
+ * `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.
+ */
+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;
+    }
+    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.
+ */
+export function isRetriableNetworkError(e) {
+    let cur = e;
+    const seen = new Set();
+    while (cur != null && !seen.has(cur)) {
+        if (typeof cur === "string") {
+            if (TRANSIENT_MESSAGE_RE.test(cur))
+                return true;
+            break;
+        }
+        if (typeof cur !== "object")
+            break;
+        seen.add(cur);
+        const err = cur;
+        // undici prefixes its own transport codes with UND_ERR_.
+        if (typeof err.code === "string" && (TRANSIENT_CODES.has(err.code) || err.code.startsWith("UND_ERR_"))) {
+            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" && TRANSIENT_MESSAGE_RE.test(err.message))
+            return true;
+        cur = err.cause;
+    }
+    // Undici's generic wrapper: assume the socket dropped and try again.
+    return e instanceof Error && /fetch failed/i.test(e.message);
+}
+/**
+ * Statuses worth re-sending, because the server (or the proxy in front of it)
+ * never produced an answer to *this* request: 408/425 mean "too slow, retry",
+ * 429 and 529 mean "overloaded, back off", and the 5xx family is a transient
+ * backend failure — a 502/503/504 from a load balancer is the HTTP face of the
+ * very connection reset the retry policy exists for.
+ *
+ * Everything else — 400, 401, 403, 404, 422 — means the request itself is wrong
+ * or the key is bad, and re-sending it would only delay the real message.
+ */
+const TRANSIENT_STATUS = new Set([408, 425, 429, 500, 502, 503, 504, 529]);
+export function isRetriableStatus(status) {
+    return TRANSIENT_STATUS.has(status);
+}
+/** A response that did arrive, but carried a failure status. */
+export class HttpStatusError extends Error {
+    status;
+    constructor(status, body) {
+        super(`HTTP ${status}${body ? " - " + body : ""}`);
+        this.name = "HttpStatusError";
+        this.status = status;
+    }
+}
+/** Whether a failure is transient, including HTTP statuses that invite a retry. */
+export function isRetriableFailure(e) {
+    if (e instanceof HttpStatusError)
+        return isRetriableStatus(e.status);
+    return isRetriableNetworkError(e);
+}
+/**
+ * Sleep before retry number `retry`, in short slices.
+ *
+ * The wait can reach 160s, so it must not be a single `setTimeout`: a paused
+ * turn or a newer message has to be able to cut it short. Returns false when
+ * `cancelled` fired, which tells the caller to stop without an error.
+ */
+export async function waitBeforeRetry(retry, policy, cancelled) {
+    const sliceMs = 100;
+    let left = retryDelayMs(retry, policy);
+    while (left > 0) {
+        if (cancelled?.())
+            return false;
+        const step = Math.min(sliceMs, left);
+        await new Promise((resolve) => setTimeout(resolve, step));
+        left -= step;
+    }
+    return !cancelled?.();
+}