@xingjisoft/neutrino 0.6.0 → 0.7.0

package/dist/web/server.js

@@ -1,3 +1,5 @@
+import { handlePlugins } from "./plugins.js";
+import { startLocalApi } from "./localApi.js";
 /**
  * A tiny, dependency-free HTTP server that exposes Neutrino to a browser.
  *
@@ -19,8 +21,10 @@ import { timingSafeEqual } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { deleteSession, listSessions, loadConfig, normalizeApprovalMode, isAgentMode, resolveModelSelection, saveConfig, sessionDir, } from "../config.js";
 import { getWebSettings, updateWebSettings } from "./settings.js";
+import { fastSettings } from "../fast/types.js";
 import { isSeenIdentity, loadSeen, updateSeen, SEEN_LIMIT } from "./clientState.js";
 import { WebAuth } from "./auth.js";
+import { pickFolder } from "./folderPicker.js";
 import { normalizeCwd, sameCwd } from "../cwd.js";
 import { hub } from "./hub.js";
 import { writeCrashLog } from "../terminal/restore.js";
@@ -451,6 +455,7 @@ function buildOverview(mode = "standard") {
         .sort((a, b) => (a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : 0));
     return {
         groups: ordered,
+        fast_mode_enabled: fastSettings(loadConfig("standard")).enabled,
         live: lives,
         generated_at: new Date().toISOString(),
     };
@@ -513,6 +518,14 @@ function isSameOrigin(req) {
         return false;
     }
 }
+/**
+ * True when the request came from this machine. The system folder window is a
+ * desktop window of the server, so only a browser beside it may ask for one.
+ */
+function isLoopbackRequest(req) {
+    const address = String(req.socket?.remoteAddress ?? "").replace(/^::ffff:/i, "");
+    return address === "::1" || address.startsWith("127.");
+}
 /** Constant-time comparison of the service's management token. */
 function hasServiceToken(req, token) {
     const header = String(req.headers.authorization ?? "");
@@ -688,7 +701,7 @@ function streamUpdateEvents(req, res, streams) {
     req.on("error", cleanup);
     res.on("error", cleanup);
 }
-async function handleApi(req, res, url, auth, mode, pathname, binding, updates) {
+async function handleApi(req, res, url, auth, mode, pathname, binding, updates, picker) {
     if (!pathname.startsWith("/api/"))
         return false;
     // The Pro presets are not bundled either: the first Pro request makes sure they
@@ -789,6 +802,10 @@ async function handleApi(req, res, url, auth, mode, pathname, binding, updates)
         sendJson(res, 401, { error: "Password login required." });
         return true;
     }
+    if (await handlePlugins(req, res, url, pathname, mode, {
+        sameOrigin: isSameOrigin(req), read: () => readJsonBody(req), json: (status, value) => sendJson(res, status, value),
+    }))
+        return true;
     // The first browser to see the background-residency prompt consumes it for
     // this console run, whether it accepted or dismissed it.
     if (pathname === "/api/background/dismiss") {
@@ -1011,6 +1028,53 @@ async function handleApi(req, res, url, auth, mode, pathname, binding, updates)
         }
         return true;
     }
+    // The working directory has to be chosen where the agent runs: a browser's
+    // own picker only exposes a folder's contents, never its absolute path. The
+    // page asks for the operating system's window instead, drawn here on the
+    // desktop. A browser on another device gets no window at all — it would open
+    // on the wrong desk — and keeps the in-page folder browser.
+    if (pathname === "/api/fs/pick") {
+        if (req.method !== "POST") {
+            sendJson(res, 405, { error: "method not allowed" });
+            return true;
+        }
+        if (!isSameOrigin(req)) {
+            sendJson(res, 403, { error: "cross-origin request rejected" });
+            return true;
+        }
+        if (!isLoopbackRequest(req)) {
+            sendJson(res, 501, { error: "the system folder window opens on this machine only", code: "native picker unavailable" });
+            return true;
+        }
+        let body;
+        try {
+            body = await readJsonBody(req, 4096);
+        }
+        catch (err) {
+            sendApiError(res, err);
+            return true;
+        }
+        const request = (body ?? {});
+        if (typeof request !== "object" || Array.isArray(request)
+            || (request.start !== undefined && typeof request.start !== "string")
+            || (request.title !== undefined && typeof request.title !== "string")) {
+            sendJson(res, 400, { error: "invalid request" });
+            return true;
+        }
+        try {
+            const outcome = await picker({ start: request.start, title: request.title });
+            if ("picked" in outcome)
+                sendJson(res, 200, { path: outcome.picked });
+            else if ("cancelled" in outcome)
+                sendJson(res, 200, { path: null });
+            else
+                sendJson(res, 501, { error: outcome.unavailable, code: "native picker unavailable" });
+        }
+        catch (err) {
+            sendApiError(res, err);
+        }
+        return true;
+    }
     // Start a brand-new conversation in a working directory chosen by the
     // browser. Unlike `/continue`, there is no transcript to load first.
     if (pathname === "/api/conversations") {
@@ -1462,7 +1526,16 @@ async function handleApi(req, res, url, auth, mode, pathname, binding, updates)
                 sendJson(res, 400, { error: "empty message" });
                 return true;
             }
-            hub.send(key, text);
+            const agentMode = body?.agent_mode;
+            if (agentMode !== undefined && (!isAgentMode(agentMode) || mode === "pro")) {
+                sendJson(res, 400, { error: "invalid agent mode" });
+                return true;
+            }
+            const sent = hub.sendConfigured(key, text, agentMode);
+            if (!sent.ok) {
+                sendJson(res, 409, { error: sent.error });
+                return true;
+            }
             sendJson(res, 200, { ok: true });
             return true;
         }
@@ -1472,7 +1545,7 @@ async function handleApi(req, res, url, auth, mode, pathname, binding, updates)
     sendJson(res, 404, { error: "not found" });
     return true;
 }
-async function handleRequest(req, res, auth, binding, updates) {
+async function handleRequest(req, res, auth, binding, updates, picker) {
     let url;
     try {
         url = new URL(req.url ?? "/", "http://localhost");
@@ -1505,7 +1578,7 @@ async function handleRequest(req, res, auth, binding, updates) {
         mode = "pro";
         apiPathname = pathname.slice("/pro".length);
     }
-    if (await handleApi(req, res, url, auth, mode, apiPathname, binding, updates))
+    if (await handleApi(req, res, url, auth, mode, apiPathname, binding, updates, picker))
         return;
     if (mode === "pro") {
         // Nothing else lives under /pro but the page and its API.
@@ -1535,11 +1608,22 @@ export async function startWebServer(options) {
         service: options.backgroundService,
         updateSettings: (body, mode) => updateSettings(body, mode),
     };
+    // One system folder window per console: a second browser asking while it is
+    // open waits for the same window instead of stacking another on the desk.
+    let folderWindow = null;
+    const openFolderWindow = (request) => {
+        if (!folderWindow) {
+            const open = options.folderPicker ?? pickFolder;
+            folderWindow = open(request).finally(() => { folderWindow = null; });
+        }
+        return folderWindow;
+    };
     // Every window watching for an update belongs to this console, not the module,
     // so a second embedded server (a test, an embedding) keeps its own set.
     const updates = createUpdateStreams();
+    let localApi = null;
     const server = http.createServer((req, res) => {
-        handleRequest(req, res, auth, binding, updates).catch((err) => {
+        handleRequest(req, res, auth, binding, updates, openFolderWindow).catch((err) => {
             if (!res.headersSent) {
                 sendJson(res, 500, { error: err instanceof Error ? err.message : "internal error" });
             }
@@ -1678,25 +1762,49 @@ export async function startWebServer(options) {
         url: "",
         urls: [],
         setHost: (next) => rebind(next),
-        close: () => new Promise((resolve) => {
-            closed = true;
-            // These streams never end on their own, so they are closed explicitly;
-            // otherwise server.close() would wait for a window that stays open.
-            updates.closeAll();
-            for (const key of [...webSessions.keys()])
-                closeWebSession(key);
-            if (!server.listening) {
-                resolve();
-                return;
-            }
-            server.close(() => resolve());
-        }),
+        close: async () => {
+            await localApi?.close();
+            localApi = null;
+            await new Promise((resolve) => {
+                closed = true;
+                // These streams never end on their own, so they are closed explicitly;
+                // otherwise server.close() would wait for a window that stays open.
+                updates.closeAll();
+                for (const key of [...webSessions.keys()])
+                    closeWebSession(key);
+                if (!server.listening) {
+                    resolve();
+                    return;
+                }
+                server.close(() => resolve());
+            });
+        },
     };
-    await listenRetry(host);
+    if (!options.apiOnly)
+        await listenRetry(host);
     // Port 0 means "let the OS pick": remember the real one for every URL.
     const address = server.address();
     port = typeof address === "object" && address ? address.port : options.port;
     syncAddress();
+    try {
+        const rawPort = process.env.NEUTRINO_API_PORT;
+        const apiPort = options.apiPort ?? (rawPort === undefined ? (options.port === 0 && !options.apiOnly ? 0 : 8766) : Number(rawPort));
+        if (!Number.isSafeInteger(apiPort) || apiPort < 0 || apiPort > 65535 || (rawPort !== undefined && !/^\d+$/.test(rawPort))) {
+            throw new Error("NEUTRINO_API_PORT must be an integer between 0 and 65535");
+        }
+        const localAuth = new WebAuth(false);
+        localApi = await startLocalApi(apiPort, async (req, res, url, mode, pathname) => {
+            if (!await handleApi(req, res, url, localAuth, mode, pathname, binding, updates, openFolderWindow)) {
+                sendJson(res, 404, { error: "not found" });
+            }
+        }, options.publishApi ?? options.port !== 0);
+        handle.api = { url: localApi.url, token: localApi.token };
+    }
+    catch (error) {
+        if (server.listening)
+            await new Promise(resolve => server.close(() => resolve()));
+        throw error;
+    }
     // Once listening, the server must tolerate connection-level failures
     // (resets, EMFILE, half-open sockets) without the process dying: an 'error'
     // event with no listener is fatal in Node.

package/dist/web/service.d.ts

@@ -0,0 +1,7 @@
+/** The detached process owns browser conversations for their entire lifetime. */
+export declare function runWebService(options: {
+    port: number;
+    host?: string;
+    auth: boolean;
+    tray: boolean;
+}): Promise<void>;

package/dist/web/service.js

@@ -120,6 +120,7 @@ export async function runWebService(options) {
     try {
         handle = await startWebServer({
             port: options.port, host: options.host, auth: options.auth,
+            publishApi: true,
             backgroundPrompt: !resident && process.env.NEUTRINO_BACKGROUND_PROMPT === "1",
             backgroundService: { token, onStop: shutdown, status, configure },
             onAddressChange: () => { if (handle)

package/dist/web/session.d.ts

@@ -0,0 +1,176 @@
+import { type AgentMode, type ModelInfo, type SessionData, type ResolvedModelSelection, type ModelSelection, type ApprovalMode, type Mode } from "../config.js";
+import { type LiveAgent, type LiveMeta, type LiveSnapshot, type ModelChangeResult } from "./hub.js";
+export type ResumeOutcome = {
+    ok: true;
+    session: WebSession;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * A fresh session id in the same shape `saveSession` generates, so a new
+ * browser conversation has a stable identity before its first message exists.
+ */
+export declare function newSessionId(now?: Date): string;
+/**
+ * Start an empty conversation in a caller-chosen working directory. Nothing is
+ * written to disk until the first message, so an abandoned new-chat dialog
+ * cannot litter the history with empty transcripts.
+ */
+export declare function createWebSession(cwd: string, selection: ResolvedModelSelection, approvalMode?: ApprovalMode, mode?: Mode, proPreset?: string, agentMode?: AgentMode): WebSession;
+/** A preset may need fallback; defer model credentials/availability to preflight. */
+export declare function proInitialSelection(preset?: string): ResolvedModelSelection;
+/**
+ * Look up the model recorded in the transcript. Returns a readable error
+ * instead of throwing, so the HTTP layer can answer with a clean 4xx.
+ */
+export declare function resolveModel(modelName: string, providerName: string): {
+    ok: true;
+    model: ModelInfo;
+} | {
+    ok: false;
+    error: string;
+};
+/** Build a web session from a saved transcript, or explain why we cannot. */
+export declare function resumeSession(source: SessionData, selection?: ModelSelection, mode?: Mode): ResumeOutcome;
+export declare class WebSession implements LiveAgent {
+    key: string | null;
+    /** Workspace this conversation belongs to; keeps Pro and standard separate. */
+    readonly mode: Mode;
+    private model;
+    private provider;
+    private intensity;
+    private readonly dir;
+    private readonly tokens;
+    private messages;
+    private sessionId;
+    private busy;
+    private approvalMode;
+    private paused;
+    private queued;
+    private compressing;
+    private context;
+    private streamingContent;
+    /** The plan of the current turn, if this turn was planned. */
+    private plan;
+    /** True while the planner agent is writing the steps. */
+    private planning;
+    private proPreset;
+    private proTeam;
+    private proState;
+    private proAbort;
+    /** What the sub-agent is doing, or null when none is running. */
+    private subagent;
+    private saveError;
+    /** A retried request, so the browser can explain why the stream is quiet. */
+    private retrying;
+    private checkpoint;
+    private taskRuntime;
+    private lastTask;
+    private taskOutcome;
+    private turnToken;
+    /** Set by a resume click: the next turn clears its tool calls without asking. */
+    private autoApproveNextTurn;
+    private autoApproveToken;
+    private agentMode;
+    private activeAgentMode;
+    private fastState?;
+    private queuedAgentMode;
+    private turnAbort;
+    private lastPromptTokens;
+    private disposed;
+    private idleTimer;
+    /** Non-null while a tool call waits for the browser to answer. */
+    private approvalQueue;
+    private pendingApproval;
+    /** Reviewer count while an automated review runs, null otherwise. */
+    private reviewing;
+    constructor(source: SessionData, model: ModelInfo, mode?: Mode);
+    /** Register with the live hub so the browser can watch this conversation. */
+    start(): string;
+    /** Detach from the hub. The transcript stays on disk. */
+    dispose(): void;
+    liveCwd(): string;
+    liveConfigure(selection: ResolvedModelSelection): ModelChangeResult;
+    liveSetProPreset(preset: string): ModelChangeResult;
+    liveMeta(): LiveMeta;
+    liveSnapshot(key: string): LiveSnapshot;
+    livePause(): void;
+    liveResume(): void;
+    liveSend(text: string): void;
+    liveApprove(approved: boolean, approvalId?: string): boolean;
+    liveSetAgentMode(mode: AgentMode): ModelChangeResult;
+    liveSetApprovalMode(mode: ApprovalMode): void;
+    /**
+     * Start a fresh chat in the same working directory, mirroring the terminal's
+     * clear shortcut. The finished transcript is checkpointed first and stays on
+     * disk; this session simply moves on under a new id.
+     */
+    liveClear(): void;
+    private send;
+    private maybeFlushQueue;
+    private startTurn;
+    /**
+     * One user turn, mirroring the terminal: plan first, then execute the steps in
+     * order, one agent loop per step. Without a usable plan the turn runs in one
+     * pass, exactly as it did before planning existed.
+     */
+    private runTurn;
+    private runTaskTurn;
+    /** Independent engine; Standard/PTC/legacy Fast retain their original loops. */
+    private runFastTurn;
+    /** Freeze one resolved team per task, plan first, then give the whole brief to main. */
+    private runProTurn;
+    /**
+     * The transcript this turn may see: the messages it started with plus what it
+     * added since. A user message queued while the turn runs belongs to the next
+     * turn, so the model never sees it early.
+     */
+    private turnView;
+    /** Move the plan to one step and publish it. */
+    private setStep;
+    /**
+     * Run the planner agent over the current request. Null on every failure path:
+     * a plan must improve a turn, never be a new way for one to fail.
+     */
+    private makePlan;
+    /** Ends a turn whose floating promise rejected, instead of crashing the app. */
+    private failTurn;
+    private buildApiMessages;
+    /**
+     * One agent conversation for a single request (or a single plan step). Returns
+     * true when the model finished on its own, false when the turn was cut short;
+     * the caller owns the turn's end because a planned turn runs this per step.
+     */
+    private agentLoop;
+    private onTurnFinished;
+    /** Classify a tool call and, when it is risky, wait for a decision. */
+    private requestApproval;
+    /** Reviewer model: `approval_model` when set, otherwise the chat model. */
+    private reviewerModel;
+    private runProgram;
+    /**
+     * Run one approved tool call. `delegate` runs a child agent instead of
+     * touching the filesystem, so it is handled here, where the session's model,
+     * approval gate and abort signal live.
+     */
+    private runTool;
+    private dispatchTool;
+    /**
+     * Run a sub-agent for one `delegate` call and return its report. The child
+     * works in its own transcript; only the report reaches this conversation, and
+     * its risky calls go through the same approval gate as the parent turn.
+     */
+    private delegate;
+    private compressThreshold;
+    /** Trim old tool results in a long turn without changing the saved history. */
+    private trimApiMessages;
+    private autoCompress;
+    private title;
+    private retainStreamingContent;
+    private save;
+    private writeSession;
+    private publishLive;
+    private touch;
+    private clearIdleTimer;
+}