@tiens.nguyen/gonext-local-worker 1.0.158 → 1.0.162

package/gonext-local-worker.mjs

@@ -5,6 +5,7 @@
  *   writes ~/.gonext/worker.env
  * - `gonext-local-worker ws-ping-test` — POST worker ws-ping (needs GONEXT_* env)
  * - `gonext-local-worker simulate-chat [text]` — claim next chat job, push fake reply like the real worker (needs GONEXT_* env)
+ * - `gonext-local-worker embed --model <mlx-embed-model> [--port 8085]` — run the MLX embeddings server (RAG); use a separate terminal
  * - `gonext-local-worker` — starts polling loop (claims jobs and runs models)
  */
 import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
@@ -221,6 +222,57 @@ if (args[0] === "ws-ping-test") {
   process.exit(0);
 }
 
+if (args[0] === "embed") {
+  // Start the MLX embeddings server (OpenAI-compatible /v1/embeddings) for the RAG
+  // feature, in the FOREGROUND of this terminal. Run it in a SEPARATE terminal from the
+  // worker (the worker keeps polling; this holds one terminal for the embed model).
+  //   gonext-local-worker embed --model ~/mlx-models/<embed-model> [--port 8085] [--host 127.0.0.1]
+  // Then set web Settings → Agent → RAG → "Embedding server URL" to http://<host>:<port>.
+  const flag = (name, fallback) => {
+    const i = args.indexOf(name);
+    return i >= 0 && typeof args[i + 1] === "string" ? args[i + 1] : fallback;
+  };
+  let model = flag("--model", process.env.GONEXT_EMBED_MODEL || "");
+  const port = flag("--port", process.env.GONEXT_EMBED_PORT || "8085");
+  const host = flag("--host", process.env.GONEXT_EMBED_HOST || "127.0.0.1");
+  if (!model) {
+    console.error(
+      "[gonext-worker] embed: --model is required.\n" +
+        "  Usage: gonext-local-worker embed --model ~/mlx-models/Qwen3-Embedding-8B-4bit-DWQ [--port 8085] [--host 127.0.0.1]\n" +
+        "  (or set GONEXT_EMBED_MODEL). Then set the RAG embedding server URL to http://<host>:<port> in web Settings."
+    );
+    process.exit(1);
+  }
+  // Expand a leading ~ to the home dir (spawn does not do shell expansion).
+  if (model.startsWith("~/") || model === "~") {
+    model = join(homedir(), model.slice(model.length > 1 ? 2 : 1));
+  }
+  const python =
+    (process.env.GONEXT_PROBE_PYTHON ?? process.env.GONEXT_MLX_LM_PYTHON ?? "").trim() ||
+    "python3";
+  const script = join(WORKER_DIR, "gonext_mlx_embed.py");
+  console.log(
+    `[gonext-worker] starting MLX embeddings server → ${python} ${script} --model ${model} --port ${port} --host ${host}`
+  );
+  const child = spawn(
+    python,
+    [script, "--model", model, "--port", String(port), "--host", String(host)],
+    { stdio: "inherit" }
+  );
+  child.on("error", (err) => {
+    console.error(`[gonext-worker] embed: failed to start python (${python}): ${err.message}`);
+    process.exit(1);
+  });
+  // Forward Ctrl-C to the child so the model unloads cleanly.
+  const stop = () => child.kill("SIGINT");
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  // Block the module from continuing to the polling loop; exit when the child exits.
+  await new Promise((resolve) => child.on("exit", (code) => resolve(code ?? 0))).then(
+    (code) => process.exit(code)
+  );
+}
+
 if (args[0] === "simulate-chat") {
   assertWorkerRuntimeConfig("simulate-chat");
   const reply =

package/gonext_agent_chat.py

@@ -1310,12 +1310,25 @@ def _embed(base: str, model: str, texts: list) -> list:
 
     # 3) Legacy Ollama /api/embeddings (per text).
     out = []
-    for t in texts:
-        data = _post(f"{root}/api/embeddings", {"model": model, "prompt": t}, 120)
-        out.append(data.get("embedding") or [])
-    if any(out):
+    try:
+        for t in texts:
+            data = _post(f"{root}/api/embeddings", {"model": model, "prompt": t}, 120)
+            out.append(data.get("embedding") or [])
+    except (urllib.error.HTTPError, urllib.error.URLError) as e:
+        code = getattr(e, "code", None)
+        raise RuntimeError(
+            f"No embeddings endpoint at {root} (tried /v1/embeddings, /api/embed, /api/embeddings; "
+            f"last HTTP {code if code else getattr(e, 'reason', e)}). Make sure an EMBEDDINGS-capable "
+            f"server is running there and the model '{model}' is available "
+            f"(e.g. `ollama pull {model}`). NOTE: mlx_lm.server does NOT serve embeddings — point the "
+            f"RAG embedding server URL at Ollama (or another embeddings server) instead."
+        )
+    if any(any(v) for v in out):
         return out
-    raise RuntimeError(f"No embedding endpoint responded at {root} ({last_err or 'unknown'}).")
+    raise RuntimeError(
+        f"Embeddings server at {root} returned empty vectors for model '{model}' "
+        f"(is '{model}' an embedding model that is installed there?)."
+    )
 
 
 def _cosine(a: list, b: list) -> float:
@@ -1349,6 +1362,24 @@ def _rag_parse_location(loc: str):
     return bucket, prefix.strip("/")
 
 
+def _rag_read_allowed(path: str) -> str:
+    """Resolve `path` and ensure it stays within a safe root (worker cwd, temp dir, or
+    ~/.gonext) — so the agent's file tools can't read arbitrary files like ~/.ssh."""
+    import os
+    import tempfile
+    rp = os.path.realpath(path)
+    roots = [
+        os.path.realpath(os.getcwd()),
+        os.path.realpath(tempfile.gettempdir()),
+        os.path.realpath(os.path.join(os.path.expanduser("~"), ".gonext")),
+    ]
+    if any(rp == r or rp.startswith(r + os.sep) for r in roots):
+        return rp
+    raise ValueError(
+        "Path is outside the allowed working directories (download/unzip outputs only)."
+    )
+
+
 def _rag_s3_client(region: str, akid: str, secret: str):
     import boto3  # noqa: PLC0415
     return boto3.client(
@@ -1724,22 +1755,29 @@ def run_agent_chat(cfg):
         _tool_num += 1
         _email_num = _tool_num
     if _RAG_AVAILABLE:
-        _tool_num += 5  # download_file, unzip_file, rag_index, rag_add, rag_search
+        _tool_num += 7  # download_file, unzip_file, list_dir, read_text_file, rag_index/add/search
     _tool_count_word = {6: "SIX", 7: "SEVEN", 8: "EIGHT"}.get(_tool_num, str(_tool_num))
     _rag_tool_block = (
-        "  KNOWLEDGE BASE (RAG) — to SUMMARIZE or ANSWER questions about a ZIP of files at a URL:\n"
+        "  FILES & KNOWLEDGE BASE — to SUMMARIZE or ANSWER questions about a ZIP of files at a URL:\n"
         "    - download_file(url) — download a file (e.g. a .zip) to this machine.\n"
         "    - unzip_file(zip_path) — extract a downloaded .zip locally.\n"
-        "    - rag_index(path, source_url) — index the unzipped text/code files into the knowledge "
-        "base (embeds to S3). source_url MUST be the ORIGINAL url the user gave.\n"
+        "    - list_dir(path) — list the files inside an unzipped folder.\n"
+        "    - read_text_file(path) — read ONE file's text (e.g. a README) directly. Best for a QUICK "
+        "project summary — you do NOT need to index for that.\n"
+        "    - rag_index(path, source_url) — index MANY text/code files into a searchable knowledge "
+        "base (embeds to S3). source_url MUST be the ORIGINAL url the user gave. Use for deep Q&A "
+        "across the whole project.\n"
         "    - rag_add(source_url, text) — add extra info the user provides to that knowledge base.\n"
         "    - rag_search(source_url, query) — retrieve the most relevant chunks to answer a question.\n"
+        "    NOTE: you may ONLY read files with these tools — plain `import os`/`open()` is blocked.\n"
     ) if _RAG_AVAILABLE else ""
     _rag_choose_line = (
-        "- user gives a URL to a ZIP of files and asks to summarize/analyze/RAG them -> "
-        "download_file(url) THEN unzip_file(zip) THEN rag_index(dir, source_url=url) THEN "
-        "rag_search(source_url=url, query=<the user's question>), THEN answer from the results. "
-        "For FOLLOW-UP questions about the SAME url, just rag_search (do NOT re-download). "
+        "- user gives a URL to a ZIP and asks to SUMMARIZE it -> download_file(url) THEN unzip_file(zip) "
+        "THEN list_dir(dir) to find the README, THEN read_text_file(that README) THEN answer from it. "
+        "This is the FASTEST path for a summary — do NOT index unless deep Q&A across many files is needed.\n"
+        "- user wants deep Q&A across the WHOLE project -> download_file THEN unzip_file THEN "
+        "rag_index(dir, source_url=url) THEN rag_search(source_url=url, query=<question>) THEN answer. "
+        "For FOLLOW-UPs on the SAME url, just rag_search (do NOT re-download). "
         "If the user adds information, rag_add(source_url=url, text=...).\n"
     ) if _RAG_AVAILABLE else ""
     _pdf_read_tool_line = (
@@ -2287,6 +2325,26 @@ def run_agent_chat(cfg):
             in_tok = out_tok = reasoning_len = 0
             first_token_at = None
 
+            # Runaway guard: a degenerate model (seen live: gemma4:26b spewing
+            # "<channel|><thought>" forever) will stream garbage until the client times
+            # out — a multi-minute hang. Abort early if the output either (a) balloons
+            # past a hard char cap, or (b) collapses into a repeating short line. On abort
+            # we return "" so the empty-turn retry re-prompts with the CODE-NOW directive.
+            _MAX_STREAM_CHARS = 16000  # a single agent step never legitimately needs this
+            _stream_buf = []           # every streamed piece (content + reasoning)
+            _stream_chars = 0
+            _runaway = False
+
+            def _looks_runaway() -> bool:
+                tail = "".join(_stream_buf)[-1600:]
+                lines = [ln.strip() for ln in tail.splitlines() if ln.strip()]
+                # 12+ of the last lines are the same short string → degenerate repetition.
+                if len(lines) >= 12:
+                    last = lines[-12:]
+                    if len(set(last)) <= 2 and all(len(ln) <= 80 for ln in last):
+                        return True
+                return False
+
             def _mark_first():
                 # First streamed byte (content OR reasoning). The gap t0→here is pure
                 # prompt-eval time (server sent nothing before this); everything after is
@@ -2324,13 +2382,33 @@ def run_agent_chat(cfg):
                 if rpiece:
                     _mark_first()
                     reasoning_len += len(rpiece)
+                    _stream_buf.append(rpiece)
+                    _stream_chars += len(rpiece)
                     _emit({"type": "stream", "text": rpiece})
                 piece = getattr(delta, "content", None)
                 if piece:
                     _mark_first()
                     parts.append(piece)
+                    _stream_buf.append(piece)
+                    _stream_chars += len(piece)
                     _emit({"type": "stream", "text": piece})
+                # Check the runaway guard periodically (cheap) once enough has streamed.
+                if _stream_chars > 500 and (_stream_chars > _MAX_STREAM_CHARS or _looks_runaway()):
+                    _runaway = True
+                    reason = "char cap" if _stream_chars > _MAX_STREAM_CHARS else "repeating output"
+                    _log(f"streamed generate: ABORTING ({reason}) after {_stream_chars} chars "
+                         "— model degenerated; closing stream.")
+                    try:
+                        stream.close()
+                    except Exception:  # noqa: BLE001
+                        pass
+                    break
             content = "".join(parts)
+            if _runaway:
+                # Discard the garbage; "" makes _streamed_generate run the CODE-NOW retry.
+                _emit({"type": "step", "text": "Model output ran away — restarting this step…"})
+                _log(f"streamed generate: discarded {len(content)} runaway chars → empty content")
+                return "", role, in_tok, out_tok, reasoning_len
             _log(f"streamed generate assembled {len(content)} chars "
                  f"(in={in_tok} out={out_tok} tokens, reasoning={reasoning_len} chars)")
             return content, role, in_tok, out_tok, reasoning_len
@@ -2665,6 +2743,55 @@ def run_agent_chat(cfg):
             except Exception as e:  # noqa: BLE001
                 return f"Error: unzip failed: {type(e).__name__}: {e}"
 
+        @tool
+        def list_dir(path: str) -> str:
+            """List files and subfolders under a local directory (from unzip_file). Use to see what files are in the project before reading or indexing them.
+
+            Args:
+                path: local directory path to list.
+            """
+            try:
+                import os
+                root = _rag_read_allowed((path or ".").strip())
+                if os.path.isfile(root):
+                    return f"{root} is a file ({os.path.getsize(root)} bytes)."
+                entries = []
+                for dirpath, dirnames, filenames in os.walk(root):
+                    dirnames[:] = [d for d in dirnames if d not in _RAG_SKIP_DIRS]
+                    for fn in filenames:
+                        rel = os.path.relpath(os.path.join(dirpath, fn), root)
+                        entries.append(rel)
+                        if len(entries) >= 300:
+                            break
+                    if len(entries) >= 300:
+                        break
+                entries.sort()
+                more = " …(truncated)" if len(entries) >= 300 else ""
+                return f"{len(entries)} files under {root}:\n" + "\n".join(entries) + more
+            except Exception as e:  # noqa: BLE001
+                return f"Error: list_dir failed: {type(e).__name__}: {e}"
+
+        @tool
+        def read_text_file(path: str, max_chars: int = 20000) -> str:
+            """Read the text contents of a single local file (e.g. a README) from a downloaded/unzipped project. Use this for a QUICK summary when you don't need full indexing.
+
+            Args:
+                path: local path to the text file (e.g. project_files/tools-hook/README.md).
+                max_chars: maximum characters to return (default 20000).
+            """
+            try:
+                import os
+                rp = _rag_read_allowed((path or "").strip())
+                if not os.path.isfile(rp):
+                    return f"Error: not a file: {path}"
+                if os.path.getsize(rp) > 5 * 1024 * 1024:
+                    return "Error: file too large to read (> 5 MB)."
+                with open(rp, "r", encoding="utf-8", errors="replace") as fh:
+                    data = fh.read(max(500, min(int(max_chars or 20000), 100000)))
+                return data or "(empty file)"
+            except Exception as e:  # noqa: BLE001
+                return f"Error: read_text_file failed: {type(e).__name__}: {e}"
+
         @tool
         def rag_index(path: str, source_url: str) -> str:
             """Index a local file or directory of TEXT/code files into the knowledge base for source_url (stores embeddings on S3). Use after unzip_file so the files become searchable. source_url MUST be the original URL the user provided.
@@ -2785,7 +2912,8 @@ def run_agent_chat(cfg):
         if _EMAIL_AVAILABLE:
             agent_tools.append(send_email)
         if _RAG_AVAILABLE:
-            agent_tools += [download_file, unzip_file, rag_index, rag_add, rag_search]
+            agent_tools += [download_file, unzip_file, list_dir, read_text_file,
+                            rag_index, rag_add, rag_search]
         agent_kwargs = dict(
             tools=agent_tools,
             model=model,

package/gonext_mlx_embed.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""
+GoNext MLX embeddings server — an OpenAI-compatible /v1/embeddings endpoint for MLX
+embedding models (e.g. Qwen3-Embedding-8B), which `mlx_lm.server` does NOT provide.
+
+The GoNext worker's RAG tools call `POST {url}/v1/embeddings` first, so pointing the
+"RAG embedding server URL" (web Settings → Agent → RAG) at this server makes MLX
+embeddings work with no other changes.
+
+Run:
+    python3 gonext_mlx_embed.py --model ~/mlx-models/Qwen3-Embedding-8B-4bit-DWQ --port 8085
+
+Then set the RAG embedding server URL to http://127.0.0.1:8085
+
+Endpoints:
+    POST /v1/embeddings   {"model": <ignored>, "input": "text" | ["t1","t2",...]}
+                          → {"object":"list","data":[{"object":"embedding","index":i,
+                             "embedding":[...]}], "model": <name>, "usage": {...}}
+    GET  /v1/models       → the single loaded model
+    GET  /health          → {"status":"ok"}
+
+Pooling: last-token hidden state (Qwen3-Embedding convention), L2-normalized.
+Requires: mlx, mlx_lm (already used by the worker). No extra deps.
+"""
+import argparse
+import json
+import os
+import sys
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+import mlx.core as mx
+from mlx_lm import load
+
+# Cap tokens per input so a pathologically long chunk can't OOM / stall the GPU.
+MAX_TOKENS = 8192
+
+_model = None
+_tok = None
+_inner = None            # the transformer body that returns hidden states
+_model_name = "mlx-embedding"
+_lock = threading.Lock()  # MLX eval isn't guaranteed thread-safe; serialize inference
+
+
+def _load(model_path: str) -> None:
+    global _model, _tok, _inner, _model_name
+    print(f"[gonext-mlx-embed] loading {model_path} …", flush=True)
+    _model, _tok = load(model_path)
+    # mlx_lm wraps the transformer body as `.model` (returns hidden states); `_model(x)`
+    # would return logits from the LM head, which we do NOT want.
+    _inner = getattr(_model, "model", None) or getattr(_model, "language_model", None)
+    if _inner is None:
+        raise RuntimeError("Could not find the transformer body on the loaded model.")
+    _model_name = os.path.basename(os.path.normpath(model_path))
+    # Warm + sanity-check the embedding path so a bad model fails fast at startup.
+    v = _embed_one("warmup")
+    print(f"[gonext-mlx-embed] ready — {_model_name}, dim={len(v)}", flush=True)
+
+
+def _embed_one(text: str) -> list:
+    ids = _tok.encode(text or " ")
+    if not ids:
+        ids = _tok.encode(" ")
+    if len(ids) > MAX_TOKENS:
+        ids = ids[:MAX_TOKENS]
+    h = _inner(mx.array([ids]))          # (1, seq, hidden)
+    v = h[0, -1, :]                       # last-token pooling
+    v = v / mx.maximum(mx.linalg.norm(v), 1e-9)   # L2 normalize
+    mx.eval(v)
+    return [float(x) for x in v.tolist()]
+
+
+def _embed_batch(texts: list) -> list:
+    with _lock:
+        out = [_embed_one(t) for t in texts]
+    return out
+
+
+class Handler(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, *a):  # quieter logs
+        pass
+
+    def _send(self, code: int, obj: dict) -> None:
+        body = json.dumps(obj).encode("utf-8")
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        if self.path == "/health":
+            self._send(200, {"status": "ok", "model": _model_name})
+        elif self.path in ("/v1/models", "/models"):
+            self._send(200, {"object": "list", "data": [
+                {"id": _model_name, "object": "model", "owned_by": "gonext-mlx-embed"}
+            ]})
+        else:
+            self._send(404, {"error": {"message": f"unknown path {self.path}"}})
+
+    def do_POST(self):
+        if self.path not in ("/v1/embeddings", "/embeddings"):
+            self._send(404, {"error": {"message": f"unknown path {self.path}"}})
+            return
+        try:
+            n = int(self.headers.get("Content-Length", 0) or 0)
+            payload = json.loads(self.rfile.read(n) or b"{}")
+        except Exception as e:  # noqa: BLE001
+            self._send(400, {"error": {"message": f"bad JSON: {e}"}})
+            return
+        inp = payload.get("input")
+        if inp is None:
+            self._send(400, {"error": {"message": "missing 'input'"}})
+            return
+        texts = [inp] if isinstance(inp, str) else list(inp)
+        if not all(isinstance(t, str) for t in texts):
+            self._send(400, {"error": {"message": "'input' must be a string or list of strings"}})
+            return
+        try:
+            vecs = _embed_batch(texts)
+        except Exception as e:  # noqa: BLE001
+            self._send(500, {"error": {"message": f"embedding failed: {type(e).__name__}: {e}"}})
+            return
+        total_tokens = sum(len(_tok.encode(t or " ")) for t in texts)
+        self._send(200, {
+            "object": "list",
+            "data": [
+                {"object": "embedding", "index": i, "embedding": v}
+                for i, v in enumerate(vecs)
+            ],
+            "model": payload.get("model") or _model_name,
+            "usage": {"prompt_tokens": total_tokens, "total_tokens": total_tokens},
+        })
+
+
+def main():
+    ap = argparse.ArgumentParser(description="OpenAI-compatible MLX embeddings server.")
+    ap.add_argument("--model", required=True, help="Path to the MLX embedding model dir.")
+    ap.add_argument("--port", type=int, default=8085)
+    ap.add_argument("--host", default="127.0.0.1")
+    args = ap.parse_args()
+    _load(os.path.expanduser(args.model))
+    srv = ThreadingHTTPServer((args.host, args.port), Handler)
+    print(f"[gonext-mlx-embed] serving /v1/embeddings on http://{args.host}:{args.port}", flush=True)
+    try:
+        srv.serve_forever()
+    except KeyboardInterrupt:
+        print("\n[gonext-mlx-embed] shutting down", flush=True)
+        srv.shutdown()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gonext-local-worker",
-  "version": "1.0.158",
+  "version": "1.0.162",
   "description": "Polls GoNext cloud API for async local LLM jobs and runs them against Ollama/OpenAI-compatible servers on this Mac",
   "type": "module",
   "license": "MIT",
@@ -25,6 +25,7 @@
     "gonext_probe_agent.py",
     "gonext_agent_chat.py",
     "gonext_transcribe.py",
+    "gonext_mlx_embed.py",
     "README.md",
     "launchd/"
   ],