neagen 0.1.6 → 0.1.7

package/README.md

@@ -1,10 +1,11 @@
 # neagen
 
-Your personal **networking agent**, in the terminal.
+**Agentic networking**, in the terminal.
 
-State a need, and your Neagen remembers who you know, finds the right person
-across your network, and prepares a warm introduction — you review and approve
-every outbound. The CLI is a thin, secure client for your hosted Neagen.
+State a need, and your Neagen represents you in the network: it finds the
+right person, prepares the introduction, and shares only what you allow. You
+review and approve every outbound. The CLI is a thin, secure client for your
+hosted Neagen.
 
 ## Install & run
 
@@ -48,6 +49,7 @@ Your passkey stays the root of your identity.
 | --- | --- | --- |
 | `NEAGEN_HOST` | `https://neagen.xyz` | Server to connect to (local dev: `http://localhost:3000`) |
 | `NEAGEN_PROFILE` | _(main)_ | Named credential slot, e.g. for multiple accounts |
+| `NEAGEN_VERBOSE` | _(off)_ | Set to `1` to show full tool output and reasoning. Off by default, so you see a short line per tool and a brief thinking indicator. Type `/verbose` in the app for the current state. |
 
 ## Where your session is stored
 

package/lib/eve-product-tui.mjs

@@ -15,7 +15,16 @@ import {
 } from "./api.mjs";
 import { runDeviceGrantLogin } from "./device-login.mjs";
 import { decorateApprovalRequests } from "./approval-format.mjs";
-import { parseSseChunk } from "./turn-stream.mjs";
+import {
+  droppedSessionFailed,
+  isBoundaryEvent,
+  neagenErrorToSessionFailed,
+  parseSseChunk,
+  readStreamChunks,
+  stalledSessionFailed,
+  TURN_STALL_MS,
+  unconfirmedBoundarySessionFailed,
+} from "./turn-stream.mjs";
 import { subscribeInboxWakeAuto } from "./wake.mjs";
 
 const require = createRequire(import.meta.url);
@@ -81,24 +90,6 @@ function isNeagenCommitEvent(eventName) {
     eventName === "neagen.gate_declined";
 }
 
-function neagenErrorToSessionFailed(data) {
-  return {
-    type: "session.failed",
-    data: {
-      error: {
-        code: data?.code ?? "turn_failed",
-        message: data?.message ?? "Turn failed.",
-      },
-    },
-  };
-}
-
-function isBoundaryEvent(event) {
-  return event?.type === "session.waiting" ||
-    event?.type === "session.completed" ||
-    event?.type === "session.failed";
-}
-
 // Swap Eve's raw "Approve tool call: <name>" prompt for a reviewable card on
 // the events that carry approval requests. Presentation only; see approval-format.mjs.
 function decorateEventData(event, data) {
@@ -111,7 +102,9 @@ function decorateEventData(event, data) {
   return data;
 }
 
-async function* readProductTurnEvents(response, onProductEvent) {
+async function* readProductTurnEvents(response, onProductEvent, options = {}) {
+  const idleMs = options.idleMs ?? TURN_STALL_MS;
+
   if (!response.ok) {
     let message = `HTTP ${response.status}`;
     const text = await response.text();
@@ -129,12 +122,22 @@ async function* readProductTurnEvents(response, onProductEvent) {
   const decoder = new TextDecoder();
   let buffer = "";
   let heldBoundary;
+  // A boundary (session.waiting/completed/failed) has been yielded to the runner.
+  // A held boundary is only released by `done` or a commit event, so a delivered
+  // boundary means the turn committed server-side. Without one the TUI keyboard
+  // never re-enables, so the tail synthesizes a terminal event.
+  let boundaryDelivered = false;
+  // A commit event (finalized/waiting_saved/gate_declined) reached us: the turn
+  // committed server-side even if its boundary or `done` never did. The tail uses
+  // this to prefer a benign completion over a scary failure.
+  let commitSeen = false;
 
   async function* handleEntry(entry) {
     const { event, data } = entry;
 
     if (event === "done") {
       if (heldBoundary) {
+        boundaryDelivered = true;
         yield heldBoundary;
         heldBoundary = undefined;
       }
@@ -142,14 +145,17 @@ async function* readProductTurnEvents(response, onProductEvent) {
     }
 
     if (event === "neagen.error") {
+      boundaryDelivered = true;
       yield neagenErrorToSessionFailed(data);
       heldBoundary = undefined;
       return;
     }
 
     if (isNeagenCommitEvent(event)) {
+      commitSeen = true;
       onProductEvent(event, data);
       if (heldBoundary) {
+        boundaryDelivered = true;
         yield heldBoundary;
         heldBoundary = undefined;
       }
@@ -164,25 +170,46 @@ async function* readProductTurnEvents(response, onProductEvent) {
     yield eveEvent;
   }
 
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    buffer += decoder.decode(value, { stream: true });
-    const parsed = parseSseChunk(buffer);
-    buffer = parsed.trailing;
-    for (const entry of parsed.events) {
-      yield* handleEntry(entry);
+  let streamError;
+  try {
+    for await (const value of readStreamChunks(reader, { idleMs })) {
+      buffer += decoder.decode(value, { stream: true });
+      const parsed = parseSseChunk(buffer);
+      buffer = parsed.trailing;
+      for (const entry of parsed.events) {
+        yield* handleEntry(entry);
+      }
     }
-  }
 
-  if (buffer.trim()) {
-    const parsed = parseSseChunk(`${buffer}\n\n`);
-    for (const entry of parsed.events) {
-      yield* handleEntry(entry);
+    if (buffer.trim()) {
+      const parsed = parseSseChunk(`${buffer}\n\n`);
+      for (const entry of parsed.events) {
+        yield* handleEntry(entry);
+      }
     }
+  } catch (error) {
+    streamError = error;
   }
 
-  if (heldBoundary) yield heldBoundary;
+  if (boundaryDelivered) return;
+
+  // The stream ended abnormally: no boundary was released in the loop (no `done`,
+  // no commit). A boundary still held here was never confirmed, so releasing it
+  // would show success for a turn that may not have committed. Decide from what
+  // we saw, always synthesizing a terminal event so the runner re-enables input.
+  if (commitSeen) {
+    // Committed server-side even without a boundary/`done` back (e.g.
+    // gate_declined sends no session boundary). Prefer a benign completion over a
+    // scary failure, on a clean end and an unclean one alike.
+    yield { type: "session.completed", data: {} };
+  } else if (heldBoundary) {
+    yield unconfirmedBoundarySessionFailed();
+  } else if (streamError?.code === "turn_stalled") {
+    yield stalledSessionFailed();
+  } else {
+    yield droppedSessionFailed();
+  }
+  heldBoundary = undefined;
 }
 
 class ProductMessageResponse {
@@ -283,6 +310,14 @@ function modelOptions(models, activeId) {
 function createModelCommandHandler({ host, token, productClient, title }) {
   return {
     async handle(command, context) {
+      if (command.name === "verbose") {
+        const on = process.env.NEAGEN_VERBOSE === "1";
+        return {
+          message: on
+            ? "Verbose display is on: full tool output and reasoning are shown. Restart with NEAGEN_VERBOSE=0 neagen to hide them again."
+            : "Neagen shows a short line per tool and a brief thinking indicator, hiding raw tool output and reasoning. To see everything, restart with NEAGEN_VERBOSE=1 neagen.",
+        };
+      }
       if (command.name !== "model") {
         return { message: `/${command.name} is not supported in the Neagen TUI.` };
       }
@@ -406,13 +441,23 @@ export async function runProductTui({ profile } = {}) {
   process.on("SIGINT", async () => { await stopWake(); process.exit(0); });
   process.on("exit", () => void wake?.close());
 
+  // Non-technical Owners get a calm transcript by default: one short line per
+  // tool call (name + args, raw bash/file/JSON output hidden) and a brief
+  // thinking indicator instead of streamed chain-of-thought. NEAGEN_VERBOSE=1
+  // restores the full developer view. The runner captures these at construction
+  // and builds its renderer once, so this is a startup choice, not a live toggle
+  // (see the /verbose command note).
+  const verbose = process.env.NEAGEN_VERBOSE === "1";
+  const partDisplay = verbose ? "full" : "collapsed";
+
   await new EveTUIRunner({
     session,
     client,
     serverUrl: host,
     name: title,
-    tools: "full",
-    reasoning: "full",
+    tools: partDisplay,
+    reasoning: partDisplay,
+    subagents: partDisplay,
     assistantResponseStats: "tokensPerSecond",
     promptCommandHandler: createModelCommandHandler({ host, token, productClient: client, title }),
     availablePromptCommands: [
@@ -432,6 +477,12 @@ export async function runProductTui({ profile } = {}) {
         argumentHint: "[all|stderr|sandbox|none]",
         takesArgument: true,
       },
+      {
+        name: "verbose",
+        aliases: [],
+        description: "How to show full tool output and reasoning",
+        takesArgument: false,
+      },
       { name: "exit", aliases: ["quit"], description: "Quit", takesArgument: false },
     ],
   }).run();

package/lib/turn-stream.mjs

@@ -6,6 +6,108 @@ function sseEvent(event, data) {
   return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
 }
 
+// Default inactivity budget for a live turn stream. If no BYTES arrive from the
+// server for this long, the connection is treated as stalled. The server sends
+// SSE heartbeat comments (`: ping`) roughly every 15s, so a healthy but quiet
+// turn keeps resetting this budget without emitting any parsed event.
+export const TURN_STALL_MS = 90000;
+
+export class TurnStallError extends Error {
+  constructor(message = "Turn stream stalled.") {
+    super(message);
+    this.name = "TurnStallError";
+    this.code = "turn_stalled";
+  }
+}
+
+export function isBoundaryEvent(event) {
+  return event?.type === "session.waiting" ||
+    event?.type === "session.completed" ||
+    event?.type === "session.failed";
+}
+
+export function neagenErrorToSessionFailed(data) {
+  return {
+    type: "session.failed",
+    data: {
+      error: {
+        code: data?.code ?? "turn_failed",
+        message: data?.message ?? "Turn failed.",
+      },
+    },
+  };
+}
+
+// Synthesized boundary for a turn whose stream went quiet past the watchdog.
+export function stalledSessionFailed() {
+  return {
+    type: "session.failed",
+    data: {
+      error: {
+        code: "turn_stalled",
+        message: "The connection to your Neagen stalled with no reply for a while. Your message may still be processing, so just send it again.",
+      },
+    },
+  };
+}
+
+// Synthesized boundary for a stream that ended (cleanly or with a network error)
+// without ever delivering a terminal boundary event. Without this the TUI runner
+// would wait forever on a boundary that is never coming and freeze the keyboard.
+export function droppedSessionFailed() {
+  return {
+    type: "session.failed",
+    data: {
+      error: {
+        code: "turn_dropped",
+        message: "The connection to your Neagen dropped mid-reply. Your message may still be processing, so just try again.",
+      },
+    },
+  };
+}
+
+// Synthesized failure for a held boundary (session.completed/waiting) that the
+// stream never confirmed with a commit event or a `done`. The boundary reached
+// us, but the turn was cut off before the server finished saving and billing it,
+// so we must not show success. The reply may have been lost mid-save.
+export function unconfirmedBoundarySessionFailed() {
+  return {
+    type: "session.failed",
+    data: {
+      error: {
+        code: "turn_unconfirmed",
+        message: "The connection to your Neagen dropped before the reply was saved. Your Neagen's reply may not have been saved, so ask again to be sure.",
+      },
+    },
+  };
+}
+
+// Reads raw byte chunks from a stream reader with an inactivity watchdog. Any
+// chunk resets the watchdog, including SSE comment bytes that parse to no event,
+// so heartbeats keep a quiet turn alive. If nothing arrives for `idleMs`, the
+// reader is cancelled and a TurnStallError is thrown. A read that rejects (a
+// mid-stream network error) is re-thrown as-is after cancelling.
+export async function* readStreamChunks(reader, { idleMs = TURN_STALL_MS } = {}) {
+  while (true) {
+    let timer;
+    const idle = new Promise((_resolve, reject) => {
+      timer = setTimeout(() => reject(new TurnStallError()), idleMs);
+      timer.unref?.();
+    });
+    let result;
+    try {
+      result = await Promise.race([reader.read(), idle]);
+    } catch (error) {
+      try { await reader.cancel(); } catch { /* best-effort */ }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+    if (result.done) return;
+    if (result.value) yield result.value;
+  }
+}
+
 export function parseSseChunk(buffer) {
   const events = [];
   const parts = buffer.split(/\n\n+/);

package/lib/wake.mjs

@@ -5,9 +5,12 @@
 // by the app + vitest). The node entrypoints are .mjs and can't import the TS
 // path-aliased module, so the same ~40 lines live here. Keep the two in sync.
 //
-// The published `neagen` CLI uses ONLY subscribeInboxWakeAbly (token auth against
-// /api/ably-token). The fs/ws transports below are for local dev / the two-agent
-// harness and are inert in the remote CLI.
+// The published `neagen` CLI calls subscribeInboxWakeAuto(ownerId, onWake, {
+// host, bearerToken }), which routes it to subscribeInboxWakeAbly (token auth
+// against /api/ably-token) since a real end user has no ABLY_API_KEY or
+// NEAGEN_WAKE_TRANSPORT set on their machine. The fs/ws transports below are for
+// local dev / the two-agent harness (dev-only x-neagen-owner header, which prod
+// rejects) and are inert in the remote CLI.
 //
 // The wake is non-polling: fs.watch is OS-level (FSEvents / inotify), event-
 // driven. "Mail = the file system" — a wake is just an envelope appearing in the
@@ -130,6 +133,12 @@ function wakeWsUrl(host) {
   return host.replace(/\/+$/, "").replace(/^http/, "ws") + "/eve/v1/wake";
 }
 
+// Give up reconnecting after this many CONSECUTIVE attempts that never reached
+// OPEN (e.g. the server rejecting the upgrade with 401 — an auth wall, not a
+// network blip). A successful open resets the counter, so genuine blips keep
+// reconnecting forever as before; only a sustained rejection wall stops the loop.
+const MAX_CONSECUTIVE_OPEN_FAILURES = 5;
+
 export async function subscribeInboxWakeWS(
   ownerId,
   onWake,
@@ -139,14 +148,19 @@ export async function subscribeInboxWakeWS(
   const url = wakeWsUrl(base);
 
   let closed = false;
+  let gaveUp = false;
   let socket;
   let reconnectTimer;
   let backoffMs = reconnectMs;
+  let consecutiveOpenFailures = 0;
 
   const connect = () => {
-    if (closed) return;
+    if (closed || gaveUp) return;
+    let openedThisAttempt = false;
     socket = new WebSocket(url, { headers: { "x-neagen-owner": ownerId } });
     socket.onopen = () => {
+      openedThisAttempt = true;
+      consecutiveOpenFailures = 0;
       backoffMs = reconnectMs; // a live connection resets the backoff
     };
     socket.onmessage = (ev) => {
@@ -167,6 +181,15 @@ export async function subscribeInboxWakeWS(
     };
     socket.onclose = () => {
       if (closed) return;
+      if (!openedThisAttempt) {
+        consecutiveOpenFailures += 1;
+        if (consecutiveOpenFailures >= MAX_CONSECUTIVE_OPEN_FAILURES) {
+          // Looks like an auth wall (e.g. prod rejecting the dev-only
+          // x-neagen-owner header with 401), not a blip — stop hammering it.
+          gaveUp = true;
+          return;
+        }
+      }
       // Exponential backoff (NOT interval polling): one-shot timer that doubles
       // up to the cap and resets on the next successful open.
       reconnectTimer = setTimeout(connect, backoffMs);
@@ -276,9 +299,13 @@ export async function subscribeInboxWakeAbly(ownerId, onWake, { key, authUrl, ho
  *   - NEAGEN_WAKE_TRANSPORT wins when set: "fs" → fs.watch (pure-local, needs a
  *     shared filesystem), "ws" → our held WebSocket to the eve wake channel,
  *     "ably" → Ably managed pub/sub.
- *   - Otherwise, if ABLY_API_KEY is set → Ably (the production default: no
- *     always-on box of our own, Ably holds the socket).
- *   - Otherwise → the held WebSocket.
+ *   - Otherwise, if ABLY_API_KEY is set → Ably with the raw key (local dev /
+ *     two-agent harness).
+ *   - Otherwise, if `host` + `bearerToken` are given → Ably via token auth
+ *     against `${host}/api/ably-token` (the published CLI: no server-side env,
+ *     no dev-only x-neagen-owner header, so the WS transport isn't reachable in
+ *     prod — token-auth Ably is the only transport a real end user can use).
+ *   - Otherwise → the held WebSocket (local dev harness, x-neagen-owner header).
  * Same (ownerId, onWake) -> { close() } contract for every transport, so callers
  * don't branch.
  */
@@ -288,6 +315,7 @@ export async function subscribeInboxWakeAuto(ownerId, onWake, options = {}) {
   if (transport === "ws") return subscribeInboxWakeWS(ownerId, onWake, options);
   if (transport === "ably") return subscribeInboxWakeAbly(ownerId, onWake, options);
   if (process.env.ABLY_API_KEY) return subscribeInboxWakeAbly(ownerId, onWake, options);
+  if (options.host && options.bearerToken) return subscribeInboxWakeAbly(ownerId, onWake, options);
   return subscribeInboxWakeWS(ownerId, onWake, options);
 }
 

package/neagen.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// neagen — your personal networking agent, in the terminal.
+// neagen: agentic networking, in the terminal.
 //
 // `neagen`            open the TUI (logs you in on first run)
 // `neagen login`      log in / refresh your session, then exit
@@ -40,7 +40,7 @@ function parseArgs(argv) {
 
 function printHelp() {
   process.stdout.write(
-    `neagen ${pkg.version} — your personal networking agent\n\n` +
+    `neagen ${pkg.version}: agentic networking, in the terminal\n\n` +
       `Usage:\n` +
       `  neagen [--profile NAME]     Open the agent (logs you in on first run)\n` +
       `  neagen login                Log in / refresh your session\n` +

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "neagen",
-  "version": "0.1.6",
-  "description": "Your personal networking agent, in the terminal. Chat, agent-mail, and files against your Neagen — passkey login, no passwords.",
+  "version": "0.1.7",
+  "description": "Agentic networking, in the terminal. Your Neagen represents you in the network: chat, agent-mail, and files, with passkey login and no passwords.",
   "type": "module",
   "bin": {
     "neagen": "neagen.mjs"
@@ -31,6 +31,7 @@
   },
   "keywords": [
     "neagen",
+    "agentic-networking",
     "networking",
     "agent",
     "cli",