@tiens.nguyen/gonext-local-worker 1.0.167 → 1.0.170

package/gonext-local-worker.mjs

@@ -6,6 +6,7 @@
  * - `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 workspace add|remove|list …` — manage local code folders the agent may read/edit/test in
  * - `gonext-local-worker` — starts polling loop (claims jobs and runs models)
  */
 import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
@@ -222,6 +223,129 @@ if (args[0] === "ws-ping-test") {
   process.exit(0);
 }
 
+if (args[0] === "workspace") {
+  // Manage the local workspaces the agent may READ and EDIT code in. Registration
+  // happens HERE on the Mac (never from the web) — the registry is the security
+  // boundary for the agent's coding tools (grep/read/edit/run stay inside these roots).
+  //   gonext-local-worker workspace add <path> [--name <name>] [--allow-run]
+  //   gonext-local-worker workspace remove <path-or-name>
+  //   gonext-local-worker workspace list
+  const wsFile = join(homedir(), ".gonext", "workspaces.json");
+  const readWs = async () => {
+    try {
+      const raw = JSON.parse(await readFile(wsFile, "utf8"));
+      return Array.isArray(raw?.workspaces) ? raw.workspaces : [];
+    } catch {
+      return [];
+    }
+  };
+  const writeWs = async (workspaces) => {
+    await mkdir(dirname(wsFile), { recursive: true });
+    await writeFile(wsFile, JSON.stringify({ workspaces }, null, 2) + "\n");
+  };
+  const sub = args[1];
+  const { resolve } = await import("node:path");
+  const { existsSync, statSync } = await import("node:fs");
+  if (sub === "add") {
+    let p = args[2] || "";
+    if (!p) {
+      console.error("Usage: gonext-local-worker workspace add <path> [--name <name>] [--allow-run]");
+      process.exit(1);
+    }
+    if (p.startsWith("~/") || p === "~") p = join(homedir(), p.slice(p.length > 1 ? 2 : 1));
+    p = resolve(p);
+    if (!existsSync(p) || !statSync(p).isDirectory()) {
+      console.error(`[gonext-worker] workspace add: not a directory: ${p}`);
+      process.exit(1);
+    }
+    const nameIdx = args.indexOf("--name");
+    const name = nameIdx >= 0 && args[nameIdx + 1] ? args[nameIdx + 1] : p.split("/").filter(Boolean).pop();
+    const allowRun = args.includes("--allow-run");
+    const list = (await readWs()).filter((w) => w.path !== p);
+    list.push({ name, path: p, allowRun, addedAt: new Date().toISOString() });
+    await writeWs(list);
+    console.log(
+      `[gonext-worker] workspace registered: ${name} → ${p}` +
+        (allowRun ? " (run-commands ENABLED)" : " (run-commands disabled; add --allow-run to enable tests)")
+    );
+    process.exit(0);
+  }
+  if (sub === "remove") {
+    const key = args[2] || "";
+    const list = await readWs();
+    const next = list.filter((w) => w.path !== key && w.name !== key);
+    if (next.length === list.length) {
+      console.error(`[gonext-worker] workspace remove: no workspace matches '${key}'`);
+      process.exit(1);
+    }
+    await writeWs(next);
+    console.log(`[gonext-worker] workspace removed: ${key}`);
+    process.exit(0);
+  }
+  if (sub === "revert") {
+    // Restore the files an agent run changed: copy backups back over edits and delete
+    // created files. Uses the manifest the python tools persist per change.
+    //   gonext-local-worker workspace revert          → latest run
+    //   gonext-local-worker workspace revert <runId>  → a specific run (see backups dir)
+    const { readdirSync, existsSync: ex } = await import("node:fs");
+    const { copyFile, unlink } = await import("node:fs/promises");
+    const backupsRoot = join(homedir(), ".gonext", "workspace-backups");
+    let runId = args[2] || "";
+    if (!runId) {
+      const runs = (() => {
+        try { return readdirSync(backupsRoot).filter((d) => !d.startsWith(".")).sort(); }
+        catch { return []; }
+      })();
+      if (runs.length === 0) {
+        console.error("[gonext-worker] workspace revert: no backup runs found.");
+        process.exit(1);
+      }
+      runId = runs[runs.length - 1];
+    }
+    const manifestPath = join(backupsRoot, runId, "manifest.json");
+    let manifest;
+    try {
+      manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    } catch {
+      console.error(`[gonext-worker] workspace revert: no manifest for run ${runId} (${manifestPath})`);
+      process.exit(1);
+    }
+    let restored = 0, deleted = 0, failed = 0;
+    for (const c of manifest?.changes ?? []) {
+      try {
+        if (c.action === "edit" && c.backup && ex(c.backup)) {
+          await copyFile(c.backup, c.path);
+          restored += 1;
+          console.log(`  restored ${c.path}`);
+        } else if (c.action === "create" && ex(c.path)) {
+          await unlink(c.path);
+          deleted += 1;
+          console.log(`  deleted  ${c.path}`);
+        }
+      } catch (err) {
+        failed += 1;
+        console.error(`  FAILED   ${c.path}: ${err.message}`);
+      }
+    }
+    console.log(
+      `[gonext-worker] workspace revert ${runId}: ${restored} restored, ${deleted} created-file(s) deleted` +
+        (failed ? `, ${failed} FAILED` : "") +
+        " (backups kept)"
+    );
+    process.exit(failed ? 1 : 0);
+  }
+  // default: list
+  const list = await readWs();
+  if (list.length === 0) {
+    console.log("[gonext-worker] no workspaces registered. Add one:\n  gonext-local-worker workspace add ~/Projects/my-repo --allow-run");
+  } else {
+    for (const w of list) {
+      console.log(`  ${w.name}  ${w.path}  run:${w.allowRun ? "yes" : "no"}`);
+    }
+  }
+  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
@@ -1631,7 +1755,10 @@ async function runAgentChatJob(job) {
       codingBaseURL: payload?.codingBaseURL ?? "",
       codingModelId: payload?.codingModelId ?? "",
       tools: payload?.tools ?? ["http_request"],
-      maxSteps: payload?.maxSteps ?? 5,
+      // 0 = "not explicitly set": python defaults to 5, but may auto-raise to 12 when
+      // workspaces are registered. Passing a literal 5 here would look user-set and
+      // block that bump.
+      maxSteps: payload?.maxSteps ?? 0,
       // Max web_search + fetch_url calls the agent may make per task (user-configurable
       // in web Settings → Agent). Default 10; past it the retrieval tools refuse.
       researchBudget: payload?.researchBudget ?? 10,
@@ -1664,6 +1791,14 @@ async function runAgentChatJob(job) {
       ragEmbedModel: payload?.ragEmbedModel ?? "",
       ragEmbedUrl: payload?.ragEmbedUrl ?? "",
       ragTopK: payload?.ragTopK ?? 6,
+      // Workspaces the agent may read/edit/test code in — read fresh each job so a
+      // `gonext-local-worker workspace add` applies without restarting the worker.
+      workspaces: await readFile(join(homedir(), ".gonext", "workspaces.json"), "utf8")
+        .then((raw) => {
+          const parsed = JSON.parse(raw);
+          return Array.isArray(parsed?.workspaces) ? parsed.workspaces : [];
+        })
+        .catch(() => []),
     });
     // 30 min max for an agent run: multi-step ReAct on a 14B/31B with a cold prompt
     // cache — or a remote Ollama box on slow GPU cold-loading a big model — can run
@@ -2260,6 +2395,20 @@ async function runLocalHealthJob(job) {
               modelPaths: modelPathStatus,
             }
           : undefined,
+      // Registered coding workspaces (names/paths only — no secrets) so the web can
+      // show which folders the agent may read/edit on this Mac.
+      workspaces: await readFile(join(homedir(), ".gonext", "workspaces.json"), "utf8")
+        .then((raw) => {
+          const parsed = JSON.parse(raw);
+          return Array.isArray(parsed?.workspaces)
+            ? parsed.workspaces.map((w) => ({
+                name: String(w.name ?? ""),
+                path: String(w.path ?? ""),
+                allowRun: Boolean(w.allowRun),
+              }))
+            : undefined;
+        })
+        .catch(() => undefined),
     };
     const totalTimeSeconds = (Date.now() - start) / 1000;
     const doneRes = await workerFetch(`/api/worker/jobs/${jobId}`, {

package/gonext_agent_chat.py

@@ -519,6 +519,8 @@ _AGENT_KEYWORDS = re.compile(
     r"|external\s+source|external\s+api|external\s+service"
     r"|web\s+service|rest\s+api|rest\s+call"
     r"|download|scrape|crawl|zip|unzip|\.zip|rag|index\s+the|knowledge\s+base|summari[sz]e"
+    r"|workspace|fix\s+(?:a\s+|the\s+|this\s+)?bug|refactor|codebase|source\s+code|repo(?:sitory)?"
+    r"|modify\s+(?:the\s+)?code|change\s+(?:the\s+)?code|run\s+(?:the\s+)?tests?"
     r"|search|find|look\s*up|lookup|weather|news|latest|current|today|tonight"
     r"|date|time|what\s+day|what\s+time"
     r"|read\s+(?:this\s+|that\s+|the\s+)?(?:page|article|url|link)|open\s+(?:this\s+|that\s+|the\s+)?(?:url|link|page)|contents?\s+of"
@@ -1417,9 +1419,16 @@ def _rag_parse_location(loc: str):
     return bucket, prefix.strip("/")
 
 
+# Registered workspace roots (from ~/.gonext/workspaces.json via the worker) — set
+# per-run by run_agent_chat. Reads are allowed in any of them; WRITES additionally
+# require _ws_write_allowed (workspace root + not inside .git/).
+_WS_ROOTS: list = []  # [{"name": str, "path": realpath str, "allowRun": bool}]
+
+
 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."""
+    """Resolve `path` and ensure it stays within a safe root (worker cwd, temp dir,
+    ~/.gonext, or a registered workspace) — so the agent's file tools can't read
+    arbitrary files like ~/.ssh."""
     import os
     import tempfile
     rp = os.path.realpath(path)
@@ -1427,14 +1436,115 @@ def _rag_read_allowed(path: str) -> str:
         os.path.realpath(os.getcwd()),
         os.path.realpath(tempfile.gettempdir()),
         os.path.realpath(os.path.join(os.path.expanduser("~"), ".gonext")),
-    ]
+    ] + [w["path"] for w in _WS_ROOTS]
     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)."
+        "Path is outside the allowed working directories (download/unzip outputs "
+        "or a registered workspace)."
     )
 
 
+def _ws_for_path(path: str):
+    """Return the registered workspace dict containing `path`, else None."""
+    import os
+    rp = os.path.realpath(path)
+    for w in _WS_ROOTS:
+        if rp == w["path"] or rp.startswith(w["path"] + os.sep):
+            return w
+    return None
+
+
+def _ws_write_allowed(path: str) -> str:
+    """Resolve `path` for WRITING: must be inside a registered workspace and never
+    inside its .git/ internals (agents must not corrupt version control)."""
+    import os
+    rp = os.path.realpath(path)
+    w = _ws_for_path(rp)
+    if w is None:
+        raise ValueError(
+            "Writes are only allowed inside a registered workspace "
+            "(register one with: gonext-local-worker workspace add <path>)."
+        )
+    rel = os.path.relpath(rp, w["path"])
+    if rel == ".git" or rel.startswith(".git" + os.sep) or (os.sep + ".git" + os.sep) in (os.sep + rel + os.sep):
+        raise ValueError("Writes inside .git/ are not allowed.")
+    return rp
+
+
+_WS_RUN_ID = None  # backup folder for this run, created lazily on first change
+_WS_CHANGES: list = []  # [{"action": "edit"|"create", "path": str, "backup": str|None}]
+
+
+def _ws_backup_root() -> str:
+    """Backup dir for this run (created lazily). Also home of manifest.json."""
+    global _WS_RUN_ID
+    import os
+    import time as _t
+    if _WS_RUN_ID is None:
+        _WS_RUN_ID = _t.strftime("%Y%m%d-%H%M%S", _t.localtime())
+    root = os.path.join(os.path.expanduser("~"), ".gonext", "workspace-backups", _WS_RUN_ID)
+    os.makedirs(root, exist_ok=True)
+    return root
+
+
+def _ws_snapshot(path: str) -> str:
+    """Copy the file to the run's backup dir before its FIRST edit in this run, so
+    every change is revertible. Returns the backup path ('' if new file)."""
+    import os
+    import shutil
+    if not os.path.isfile(path):
+        return ""
+    for c in _WS_CHANGES:  # already snapshotted this run — keep the ORIGINAL version
+        if c["path"] == path and c.get("backup"):
+            return c["backup"]
+    root = _ws_backup_root()
+    dest = os.path.join(root, path.lstrip(os.sep))
+    os.makedirs(os.path.dirname(dest), exist_ok=True)
+    shutil.copy2(path, dest)
+    return dest
+
+
+def _ws_record_change(action: str, path: str, backup) -> None:
+    """Track a change AND persist the run manifest so `gonext-local-worker workspace
+    revert` can restore edits / delete created files after the process is gone."""
+    import os
+    _WS_CHANGES.append({"action": action, "path": path, "backup": backup or None})
+    try:
+        root = _ws_backup_root()
+        with open(os.path.join(root, "manifest.json"), "w", encoding="utf-8") as fh:
+            json.dump({"changes": _WS_CHANGES}, fh, indent=2)
+    except OSError as e:
+        _log(f"workspace manifest write failed: {e}")
+
+
+# Command prefixes run_command may execute (first token after shlex split). Build/test
+# runners only — no shells, no package publishes, no sudo.
+_WS_RUN_ALLOWED = {
+    "npm", "npx", "yarn", "pnpm", "node", "mvn", "./mvnw", "gradle", "./gradlew",
+    "pytest", "python", "python3", "go", "cargo", "make", "dotnet", "swift",
+    "rspec", "bundle", "php", "composer", "tsc", "jest", "vitest",
+}
+
+
+def _ws_scrubbed_env() -> dict:
+    """Minimal child env for run_command. The worker process env holds secrets
+    (GONEXT_WORKER_KEY etc. via worker.env) — a repo's test script must NEVER see
+    them, so we pass an explicit whitelist instead of inheriting."""
+    import os
+    keep = ("PATH", "HOME", "LANG", "LC_ALL", "TMPDIR", "SHELL", "USER", "TERM",
+            "JAVA_HOME", "GOPATH", "CARGO_HOME", "NVM_DIR")
+    return {k: os.environ[k] for k in keep if k in os.environ}
+
+
+def _ws_distill_output(out: str, cap_head: int = 1200, cap_tail: int = 4000) -> str:
+    """Cap huge build/test output: failures live at the tail, context at the head."""
+    if len(out) <= cap_head + cap_tail + 200:
+        return out
+    return (out[:cap_head] + f"\n…[{len(out) - cap_head - cap_tail} chars omitted]…\n"
+            + out[-cap_tail:])
+
+
 def _rag_s3_client(region: str, akid: str, secret: str):
     import boto3  # noqa: PLC0415
     return boto3.client(
@@ -1627,6 +1737,33 @@ def run_agent_chat(cfg):
     if rag_enabled and not _boto3_ok:
         _log("RAG requested but boto3 is not installed in the worker python — RAG tools disabled")
 
+    # ---- Workspaces (local folders the agent may read/edit/test code in) ----
+    # Registered on the Mac via `gonext-local-worker workspace add <path>`; the worker
+    # passes the registry through cfg. Only these roots are writable — the security
+    # boundary for the coding tools.
+    global _WS_ROOTS
+    _WS_ROOTS = []
+    for w in (cfg.get("workspaces") or []):
+        try:
+            import os as _os
+            p = _os.path.realpath(_os.path.expanduser(str(w.get("path") or "")))
+            if p and _os.path.isdir(p):
+                _WS_ROOTS.append({
+                    "name": str(w.get("name") or _os.path.basename(p)),
+                    "path": p,
+                    "allowRun": bool(w.get("allowRun")),
+                })
+        except Exception:  # noqa: BLE001
+            continue
+    _WS_AVAILABLE = bool(_WS_ROOTS)
+    if _WS_AVAILABLE:
+        _log(f"workspaces: {[(w['name'], w['path'], w['allowRun']) for w in _WS_ROOTS]}")
+        # Coding tasks are edit→test→fix loops — 5 steps is too tight. Bump the default
+        # budget when workspaces are registered, unless the payload set one explicitly.
+        if not cfg.get("maxSteps") and max_steps < 12:
+            max_steps = 12
+            _log("workspace registered → step budget raised to 12 (no explicit maxSteps)")
+
     def _rag_s3_and_loc():
         client = _rag_s3_client(rag_region, rag_akid, rag_secret)
         bucket, prefix = _rag_parse_location(rag_location)
@@ -1811,6 +1948,10 @@ def run_agent_chat(cfg):
         _email_num = _tool_num
     if _RAG_AVAILABLE:
         _tool_num += 7  # download_file, unzip_file, list_dir, read_text_file, rag_index/add/search
+    if _WS_AVAILABLE:
+        _tool_num += 6  # grep_repo, read_file_lines, edit_lines, edit_file, create_file, run_command
+        if not _RAG_AVAILABLE:
+            _tool_num += 2  # list_dir + read_text_file registered for workspace browsing
     _tool_count_word = {6: "SIX", 7: "SEVEN", 8: "EIGHT"}.get(_tool_num, str(_tool_num))
     _rag_tool_block = (
         "  FILES & KNOWLEDGE BASE — to SUMMARIZE or ANSWER questions about a ZIP of files at a URL:\n"
@@ -1838,6 +1979,33 @@ def run_agent_chat(cfg):
         "instantly — then list_dir/read_text_file or rag_index as needed. "
         "If the user adds information, rag_add(source_url=url, text=...).\n"
     ) if _RAG_AVAILABLE else ""
+    _ws_names = ", ".join(f"{w['name']} = {w['path']}" for w in _WS_ROOTS)
+    _ws_tool_block = (
+        f"  WORKSPACES (local code folders you may READ and EDIT): {_ws_names}\n"
+        "    - list_dir(path) / read_text_file(path) — browse and read files.\n"
+        "    - grep_repo(pattern, path='', glob='') — search code, returns file:line hits. "
+        "Use this to find the EXACT lines to change.\n"
+        "    - read_file_lines(path, start_line, end_line) — read WITH line numbers "
+        "before editing.\n"
+        "    - edit_lines(path, start_line, end_line, new_content) — PRIMARY edit tool: "
+        "replace a line range (backup saved automatically).\n"
+        "    - edit_file(path, old_string, new_string) — replace one exact unique string "
+        "(must match byte-for-byte; prefer edit_lines).\n"
+        "    - create_file(path, content) — create a NEW file.\n"
+        "    - run_command(command, workdir='') — run a build/test command (npm test, mvn "
+        "test, pytest…) to VERIFY changes (only in workspaces with run permission).\n"
+        "    NOTE: plain `import os`/`open()` is blocked — use ONLY these tools for files.\n"
+    ) if _WS_AVAILABLE else ""
+    _ws_choose_line = (
+        "- user asks to FIX A BUG / MODIFY / ADD CODE in a workspace -> "
+        "grep_repo(pattern) (and/or rag_search if indexed) to FIND the file, THEN "
+        "read_file_lines(file, around the hit) to see exact lines, THEN "
+        "edit_lines(file, start, end, new_content) to change them, THEN "
+        "run_command('…test…') to VERIFY if run permission exists — read failures and fix, "
+        "iterate. Finish with final_answer summarizing WHAT you changed (files + lines). "
+        "AFTER editing, re-read with grep_repo/read_file_lines (an S3 knowledge base may be "
+        "stale — do not trust rag_search for freshly edited code).\n"
+    ) if _WS_AVAILABLE else ""
     _pdf_read_tool_line = (
         f"  {_pdf_num}. extract_text_from_pdf(url) — READ/summarize an EXISTING PDF file "
         "at a URL. This does NOT create a PDF (use create_pdf for that).\n"
@@ -1874,7 +2042,7 @@ def run_agent_chat(cfg):
         "Use this ONLY when the task explicitly asks for the date or time.\n"
         "  6. create_pdf(text, title='') — make a PDF document from text/data and return a "
         "download link. Use ONLY when the task asks to create/make/generate/export a PDF.\n"
-        + _pdf_read_tool_line + _email_tool_line + _rag_tool_block +
+        + _pdf_read_tool_line + _email_tool_line + _rag_tool_block + _ws_tool_block +
         "\n"
         "http_request RETURN FORMAT: 'HTTP 200\\n{body}' — first line is 'HTTP <code>', body follows.\n"
         "\n"
@@ -1898,7 +2066,7 @@ def run_agent_chat(cfg):
         "- a PDF of info you must LOOK UP first (e.g. 'get the world cup schedule then make a "
         "pdf') -> FIRST web_search/fetch_url to gather the real facts, THEN in a later step "
         "create_pdf(text=<the gathered facts>, title=...). Never PDF the request wording itself.\n"
-        + _pdf_read_choose_line + _email_choose_line + _rag_choose_line +
+        + _pdf_read_choose_line + _email_choose_line + _rag_choose_line + _ws_choose_line +
         "- A specific known API/URL was given -> http_request().\n"
         "\n"
         "RULES:\n"
@@ -2998,6 +3166,198 @@ def run_agent_chat(cfg):
             except Exception as e:  # noqa: BLE001
                 return f"Error: rag_search failed: {type(e).__name__}: {e}"
 
+        @tool
+        def grep_repo(pattern: str, path: str = "", glob: str = "") -> str:
+            """Search text files for a pattern (regex or literal) and return file:line hits. Use to find the EXACT lines to edit after rag_search located the relevant area.
+
+            Args:
+                pattern: regex (or literal text) to search for.
+                path: directory to search (a workspace or unzipped folder). Empty = first registered workspace.
+                glob: optional filename filter, e.g. "*.java" or "*Controller*".
+            """
+            try:
+                import fnmatch
+                import os
+                root = _rag_read_allowed((path or "").strip() or (_WS_ROOTS[0]["path"] if _WS_ROOTS else "."))
+                try:
+                    rx = re.compile(pattern)
+                except re.error:
+                    rx = re.compile(re.escape(pattern))
+                hits = []
+                for abs_path, rel, _ext in _rag_iter_text_files(root):
+                    if glob and not fnmatch.fnmatch(os.path.basename(rel), glob) \
+                            and not fnmatch.fnmatch(rel, glob):
+                        continue
+                    try:
+                        with open(abs_path, "r", encoding="utf-8", errors="replace") as fh:
+                            for i, line in enumerate(fh, 1):
+                                if rx.search(line):
+                                    hits.append(f"{rel}:{i}: {line.rstrip()[:200]}")
+                                    if len(hits) >= 100:
+                                        break
+                    except OSError:
+                        continue
+                    if len(hits) >= 100:
+                        break
+                _emit({"type": "step", "text": f"Searching code → {pattern[:60]} ({len(hits)} hits)"})
+                if not hits:
+                    return f"No matches for {pattern!r} under {root}."
+                more = "\n…(capped at 100 hits)" if len(hits) >= 100 else ""
+                return f"Matches under {root}:\n" + "\n".join(hits) + more
+            except Exception as e:  # noqa: BLE001
+                return f"Error: grep_repo failed: {type(e).__name__}: {e}"
+
+        @tool
+        def read_file_lines(path: str, start_line: int = 1, end_line: int = 0) -> str:
+            """Read a file with LINE NUMBERS (for locating code before edit_lines). end_line 0 = to end (capped).
+
+            Args:
+                path: local file path.
+                start_line: first line to show (1-based).
+                end_line: last line to show inclusive; 0 = rest of file (max 400 lines shown).
+            """
+            try:
+                rp = _rag_read_allowed((path or "").strip())
+                with open(rp, "r", encoding="utf-8", errors="replace") as fh:
+                    lines = fh.readlines()
+                s = max(1, int(start_line or 1))
+                e = int(end_line or 0) or len(lines)
+                e = min(e, len(lines), s + 399)
+                body = "".join(f"{i}: {lines[i - 1]}" for i in range(s, e + 1))
+                return f"{rp} (lines {s}-{e} of {len(lines)}):\n{body}"
+            except Exception as ex:  # noqa: BLE001
+                return f"Error: read_file_lines failed: {type(ex).__name__}: {ex}"
+
+        @tool
+        def edit_lines(path: str, start_line: int, end_line: int, new_content: str) -> str:
+            """Replace lines start_line..end_line (inclusive, 1-based) of a workspace file with new_content. The PRIMARY edit tool — get exact line numbers from grep_repo/read_file_lines first. A backup is saved automatically.
+
+            Args:
+                path: file inside a registered workspace.
+                start_line: first line to replace (1-based).
+                end_line: last line to replace (inclusive).
+                new_content: replacement text (may be more or fewer lines).
+            """
+            try:
+                rp = _ws_write_allowed((path or "").strip())
+                import os
+                if not os.path.isfile(rp):
+                    return f"Error: not a file: {path}"
+                backup = _ws_snapshot(rp)
+                with open(rp, "r", encoding="utf-8", errors="replace") as fh:
+                    lines = fh.readlines()
+                s, e = int(start_line), int(end_line)
+                if not (1 <= s <= e <= len(lines)):
+                    return (f"Error: line range {s}-{e} is out of bounds "
+                            f"(file has {len(lines)} lines). Re-check with read_file_lines.")
+                new_lines = new_content.splitlines(keepends=True)
+                if new_lines and not new_lines[-1].endswith("\n"):
+                    new_lines[-1] += "\n"
+                lines[s - 1:e] = new_lines
+                with open(rp, "w", encoding="utf-8") as fh:
+                    fh.writelines(lines)
+                _ws_record_change("edit", rp, backup)
+                _emit({"type": "step", "text": f"Edited {os.path.basename(rp)} lines {s}-{e}"})
+                shown = "".join(f"{i}: {lines[i - 1]}" for i in
+                                range(max(1, s - 2), min(len(lines), s + len(new_lines) + 1) + 1))
+                return (f"Replaced lines {s}-{e} of {rp} with {len(new_lines)} line(s). "
+                        f"Backup saved. Updated region:\n{shown}")
+            except Exception as ex:  # noqa: BLE001
+                return f"Error: edit_lines failed: {type(ex).__name__}: {ex}"
+
+        @tool
+        def edit_file(path: str, old_string: str, new_string: str) -> str:
+            """Replace an EXACT unique text occurrence in a workspace file (must match byte-for-byte incl. whitespace). Prefer edit_lines when you have line numbers. A backup is saved automatically.
+
+            Args:
+                path: file inside a registered workspace.
+                old_string: exact existing text to replace (must occur exactly once).
+                new_string: replacement text.
+            """
+            try:
+                rp = _ws_write_allowed((path or "").strip())
+                import os
+                if not os.path.isfile(rp):
+                    return f"Error: not a file: {path}"
+                with open(rp, "r", encoding="utf-8", errors="replace") as fh:
+                    text = fh.read()
+                n = text.count(old_string)
+                if n == 0:
+                    return ("Error: old_string not found — it must match EXACTLY "
+                            "(check whitespace with read_file_lines, or use edit_lines).")
+                if n > 1:
+                    return f"Error: old_string occurs {n} times — add surrounding context to make it unique, or use edit_lines."
+                backup = _ws_snapshot(rp)
+                with open(rp, "w", encoding="utf-8") as fh:
+                    fh.write(text.replace(old_string, new_string, 1))
+                _ws_record_change("edit", rp, backup)
+                _emit({"type": "step", "text": f"Edited {os.path.basename(rp)}"})
+                return f"Replaced 1 occurrence in {rp}. Backup saved."
+            except Exception as ex:  # noqa: BLE001
+                return f"Error: edit_file failed: {type(ex).__name__}: {ex}"
+
+        @tool
+        def create_file(path: str, content: str) -> str:
+            """Create a NEW file inside a registered workspace (errors if it already exists — use edit tools for existing files).
+
+            Args:
+                path: new file path inside a workspace.
+                content: full file content.
+            """
+            try:
+                rp = _ws_write_allowed((path or "").strip())
+                import os
+                if os.path.exists(rp):
+                    return f"Error: {path} already exists — use edit_lines/edit_file to change it."
+                os.makedirs(os.path.dirname(rp) or ".", exist_ok=True)
+                with open(rp, "w", encoding="utf-8") as fh:
+                    fh.write(content)
+                _ws_record_change("create", rp, None)
+                _emit({"type": "step", "text": f"Created {os.path.basename(rp)}"})
+                return f"Created {rp} ({len(content)} chars)."
+            except Exception as ex:  # noqa: BLE001
+                return f"Error: create_file failed: {type(ex).__name__}: {ex}"
+
+        @tool
+        def run_command(command: str, workdir: str = "", timeout_seconds: int = 180) -> str:
+            """Run a build/test command inside a workspace that has run permission (e.g. 'npm test', 'mvn test', 'pytest'). Use to VERIFY code changes; read the output and fix failures.
+
+            Args:
+                command: the command line (build/test runners only; no shells or sudo).
+                workdir: directory to run in. Empty = first registered workspace.
+                timeout_seconds: kill the command after this many seconds (max 600).
+            """
+            try:
+                import os
+                import shlex
+                import subprocess
+                wd = _rag_read_allowed((workdir or "").strip() or (_WS_ROOTS[0]["path"] if _WS_ROOTS else "."))
+                w = _ws_for_path(wd)
+                if w is None or not w.get("allowRun"):
+                    return ("Error: running commands is not enabled for this workspace. "
+                            "Re-register it with: gonext-local-worker workspace add <path> --allow-run")
+                argv = shlex.split(command or "")
+                if not argv:
+                    return "Error: empty command."
+                if argv[0] not in _WS_RUN_ALLOWED:
+                    return (f"Error: '{argv[0]}' is not an allowed runner. Allowed: "
+                            + ", ".join(sorted(_WS_RUN_ALLOWED)))
+                _emit({"type": "step", "text": f"Running → {command[:70]}"})
+                t = max(5, min(int(timeout_seconds or 180), 600))
+                # Scrubbed env: repo test scripts must never see worker secrets.
+                proc = subprocess.run(
+                    argv, cwd=wd, env=_ws_scrubbed_env(), timeout=t,
+                    stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+                )
+                out = _ws_distill_output(proc.stdout or "")
+                status = "PASSED (exit 0)" if proc.returncode == 0 else f"FAILED (exit {proc.returncode})"
+                _emit({"type": "step", "text": f"Command {status.split()[0].lower()} → {command[:50]}"})
+                return f"{status}\n{out}" if out.strip() else status
+            except subprocess.TimeoutExpired:
+                return f"Error: command timed out after {timeout_seconds}s."
+            except Exception as ex:  # noqa: BLE001
+                return f"Error: run_command failed: {type(ex).__name__}: {ex}"
+
         agent_tools = [http_request, web_search, fetch_url, calculate,
                        get_current_datetime, create_pdf]
         # Only register the PDF reader / email / RAG tools when available (kept in sync
@@ -3009,6 +3369,13 @@ def run_agent_chat(cfg):
         if _RAG_AVAILABLE:
             agent_tools += [download_file, unzip_file, list_dir, read_text_file,
                             rag_index, rag_add, rag_search]
+        if _WS_AVAILABLE:
+            agent_tools += [grep_repo, read_file_lines, edit_lines, edit_file,
+                            create_file, run_command]
+            # list_dir/read_text_file are needed for workspace browsing even when RAG
+            # (S3 indexing) isn't configured.
+            if not _RAG_AVAILABLE:
+                agent_tools += [list_dir, read_text_file]
         agent_kwargs = dict(
             tools=agent_tools,
             model=model,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gonext-local-worker",
-  "version": "1.0.167",
+  "version": "1.0.170",
   "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",