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

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-repl.mjs

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+/**
+ * `gonext` — terminal agent REPL (P6).
+ *
+ * Run it inside any project folder:
+ *   $ cd ~/Projects/my-repo
+ *   $ gonext
+ *
+ * It offers to register the CURRENT folder as an agent workspace (with a trust prompt
+ * that maps to --allow-run), authenticates with the worker key from ~/.gonext/worker.env
+ * (the same file `gonext-local-worker set` / the Wizard write), pulls your agent/coding
+ * model + budgets + RAG config FROM YOUR USER SETTINGS via POST /api/worker/agent-payload,
+ * then loops on a `>> ` prompt. Each question executes gonext_agent_chat.py DIRECTLY
+ * (no job queue — no race with a polling worker daemon), streaming the agent's steps
+ * and thinking into the terminal.
+ *
+ * Commands: /exit  /revert [runId]  /help      Ctrl-C aborts the current run.
+ */
+import { readFile, mkdir, writeFile } from "node:fs/promises";
+import { existsSync, statSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { dirname, join, resolve, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+import dotenv from "dotenv";
+
+const DIR = dirname(fileURLToPath(import.meta.url));
+const ENV_FILE = join(homedir(), ".gonext", "worker.env");
+const WS_FILE = join(homedir(), ".gonext", "workspaces.json");
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+
+// ---------- auth: worker key + API base from ~/.gonext/worker.env ----------
+dotenv.config({ path: ENV_FILE });
+dotenv.config();
+const workerKey = String(process.env.GONEXT_WORKER_KEY ?? "").trim();
+const apiBase = String(process.env.GONEXT_API_BASE ?? "").trim().replace(/\/+$/, "");
+if (!workerKey || !apiBase) {
+  console.error(
+    red("gonext: no worker key / API base found.") +
+      `\nExpected ${ENV_FILE} (written by the Installation Wizard), or configure manually:` +
+      "\n  gonext-local-worker set <workerKey> --api-base https://chat-api-v2.gomarsic.cc"
+  );
+  process.exit(1);
+}
+
+// Line intake: attach the listener IMMEDIATELY so lines that arrive while startup
+// awaits (workspace prompt fetch, payload probe) are queued instead of lost — vital
+// for piped/scripted input, harmless for interactive TTYs. Both ask() and the main
+// loop consume from this queue (never rl.question, to avoid double-capture).
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+const _lineQueue = [];
+let _lineWaiter = null;
+let _stdinClosed = false;
+rl.on("line", (l) => {
+  if (_lineWaiter) {
+    const w = _lineWaiter;
+    _lineWaiter = null;
+    w(l);
+  } else {
+    _lineQueue.push(l);
+  }
+});
+rl.on("close", () => {
+  _stdinClosed = true;
+  if (_lineWaiter) {
+    const w = _lineWaiter;
+    _lineWaiter = null;
+    w(null);
+  }
+});
+const nextLine = () =>
+  _lineQueue.length > 0
+    ? Promise.resolve(_lineQueue.shift())
+    : _stdinClosed
+      ? Promise.resolve(null)
+      : new Promise((res) => (_lineWaiter = res));
+const ask = async (q) => {
+  process.stdout.write(q);
+  const a = await nextLine();
+  return (a ?? "").trim();
+};
+
+// ---------- workspace registration for the current folder ----------
+async function readWorkspaces() {
+  try {
+    const raw = JSON.parse(await readFile(WS_FILE, "utf8"));
+    return Array.isArray(raw?.workspaces) ? raw.workspaces : [];
+  } catch {
+    return [];
+  }
+}
+
+async function ensureWorkspace() {
+  const cwd = resolve(process.cwd());
+  const list = await readWorkspaces();
+  const hit = list.find((w) => cwd === w.path || cwd.startsWith(w.path + "/"));
+  if (hit) {
+    console.log(
+      dim(`workspace: ${hit.name} → ${hit.path} (run ${hit.allowRun ? "enabled" : "disabled"})`)
+    );
+    return;
+  }
+  if (!existsSync(cwd) || !statSync(cwd).isDirectory()) return;
+  console.log(`This folder is not a registered workspace:\n  ${cwd}`);
+  const reg = (await ask("Register it so the agent can read/edit code here? [Y/n] ")) || "y";
+  if (!/^y(es)?$/i.test(reg)) {
+    console.log(dim("Skipped — the agent will not be able to touch files here."));
+    return;
+  }
+  const trust = (await ask(
+    "Do you trust this folder — allow the agent to RUN build/test commands\n" +
+      "(npm test, mvn, pytest…)? [y/N] "
+  )) || "n";
+  const allowRun = /^y(es)?$/i.test(trust);
+  const next = list.filter((w) => w.path !== cwd);
+  next.push({
+    name: basename(cwd),
+    path: cwd,
+    allowRun,
+    addedAt: new Date().toISOString(),
+  });
+  await mkdir(dirname(WS_FILE), { recursive: true });
+  await writeFile(WS_FILE, JSON.stringify({ workspaces: next }, null, 2) + "\n");
+  console.log(
+    green(`✓ workspace registered: ${basename(cwd)}`) +
+      (allowRun ? green(" (run-commands enabled)") : dim(" (run-commands disabled)"))
+  );
+}
+
+// ---------- fetch the ready-to-run agent payload from user settings ----------
+async function fetchAgentPayload(messages) {
+  const res = await fetch(`${apiBase}/api/worker/agent-payload`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "X-Worker-Key": workerKey },
+    body: JSON.stringify({ messages }),
+  });
+  const text = await res.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = {};
+  }
+  if (!res.ok) {
+    if (res.status === 404) {
+      throw new Error(
+        "the API does not have POST /api/worker/agent-payload yet — deploy the latest API (sam build && sam deploy)."
+      );
+    }
+    throw new Error(data?.error || `agent-payload failed (HTTP ${res.status})`);
+  }
+  return data;
+}
+
+// ---------- run one agent turn by executing gonext_agent_chat.py directly ----------
+let child = null;
+
+async function runAgentTurn(payload) {
+  // Map the job payload to the python cfg the same way the worker daemon does in
+  // runAgentChatJob (gonext-local-worker.mjs) — KEEP IN SYNC with that block.
+  const input = JSON.stringify({
+    messages: payload?.messages ?? [],
+    agentBaseURL: payload?.agentBaseURL ?? "",
+    agentApiKey: payload?.agentApiKey ?? "",
+    agentModelId: payload?.agentModelId ?? "",
+    codingBaseURL: payload?.codingBaseURL ?? "",
+    codingModelId: payload?.codingModelId ?? "",
+    tools: payload?.tools ?? ["http_request"],
+    maxSteps: payload?.maxSteps ?? 0,
+    researchBudget: payload?.researchBudget ?? 10,
+    agentToolMode: payload?.agentToolMode ?? "code",
+    apiBaseURL: apiBase,
+    workerKey,
+    emailEnabled: payload?.emailEnabled ?? false,
+    emailApiUrl: payload?.emailApiUrl ?? "",
+    emailApiMethod: payload?.emailApiMethod ?? "POST",
+    emailApiHeaders: payload?.emailApiHeaders ?? "",
+    emailBodyTemplate: payload?.emailBodyTemplate ?? "",
+    emailFrom: payload?.emailFrom ?? "",
+    emailAllowList: payload?.emailAllowList ?? "",
+    ragEnabled: payload?.ragEnabled ?? false,
+    ragS3Location: payload?.ragS3Location ?? "",
+    ragAwsRegion: payload?.ragAwsRegion ?? "",
+    ragAwsAccessKeyId: payload?.ragAwsAccessKeyId ?? "",
+    ragAwsSecretAccessKey: payload?.ragAwsSecretAccessKey ?? "",
+    ragEmbedModel: payload?.ragEmbedModel ?? "",
+    ragEmbedUrl: payload?.ragEmbedUrl ?? "",
+    ragTopK: payload?.ragTopK ?? 6,
+    workspaces: await readWorkspaces(),
+  });
+
+  const python =
+    (process.env.GONEXT_PROBE_PYTHON ?? process.env.GONEXT_MLX_LM_PYTHON ?? "").trim() ||
+    "python3";
+  // WeasyPrint (create_pdf) needs Homebrew libs on macOS — same env the worker sets.
+  let extraEnv;
+  if (process.platform === "darwin") {
+    const existing = process.env.DYLD_FALLBACK_LIBRARY_PATH ?? "";
+    extraEnv = {
+      DYLD_FALLBACK_LIBRARY_PATH: [existing, "/opt/homebrew/lib", "/usr/local/lib"]
+        .filter(Boolean)
+        .join(":"),
+    };
+  }
+
+  return new Promise((resolveTurn) => {
+    let finalText = "";
+    let buf = "";
+    child = spawn(python, [join(DIR, "gonext_agent_chat.py")], {
+      env: { ...process.env, ...(extraEnv ?? {}) },
+    });
+    child.stdin.write(input);
+    child.stdin.end();
+    child.stdout.on("data", (chunk) => {
+      buf += chunk.toString();
+      let nl;
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        if (!line.trim()) continue;
+        let ev;
+        try {
+          ev = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (ev.type === "step" && typeof ev.text === "string") {
+          process.stdout.write(dim(`\n· ${ev.text}`));
+        } else if (ev.type === "stream" && typeof ev.text === "string") {
+          process.stdout.write(dim(ev.text));
+        } else if (ev.type === "final" && typeof ev.text === "string") {
+          finalText = ev.text;
+        } else if (ev.type === "log" && process.env.GONEXT_REPL_VERBOSE === "1") {
+          process.stdout.write(dim(`\n[log] ${ev.text}`));
+        }
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      if (process.env.GONEXT_REPL_VERBOSE === "1") {
+        process.stderr.write(dim(chunk.toString()));
+      }
+    });
+    child.on("error", (err) => {
+      console.error(red(`\ngonext: failed to start ${python}: ${err.message}`));
+      child = null;
+      resolveTurn("");
+    });
+    child.on("exit", () => {
+      child = null;
+      resolveTurn(finalText);
+    });
+  });
+}
+
+// ---------- REPL ----------
+async function main() {
+  console.log(cyan("GoNext agent REPL") + dim(` · API ${apiBase} · key ${workerKey.slice(0, 8)}…`));
+  await ensureWorkspace();
+  // Show which models will answer, straight from user settings (also validates auth).
+  try {
+    const probe = await fetchAgentPayload([{ role: "user", content: "ping" }]);
+    const p = probe?.payload ?? {};
+    console.log(
+      dim(
+        `agent model: ${p.agentModelId || probe?.modelKey || "?"}` +
+          (p.codingModelId ? ` · coder: ${p.codingModelId}` : "") +
+          (p.ragEnabled ? " · RAG on" : "")
+      )
+    );
+  } catch (err) {
+    console.error(red(`gonext: ${err.message}`));
+    process.exit(1);
+  }
+  console.log(dim("Ask about this repo, or /help. Ctrl-C aborts a running turn.\n"));
+
+  const history = [];
+  rl.on("SIGINT", () => {
+    if (child) {
+      child.kill("SIGKILL");
+      child = null;
+      process.stdout.write(red("\n^C run aborted\n"));
+    } else {
+      process.stdout.write(dim("\n(/exit to quit)\n") + cyan(">> "));
+    }
+  });
+
+  for (;;) {
+    process.stdout.write(cyan(">> "));
+    const lineRaw = await nextLine();
+    if (lineRaw === null) break; // stdin closed
+    const line = lineRaw.trim();
+    if (!line) continue;
+    if (line === "/exit" || line === "/quit") break;
+    if (line === "/help") {
+      console.log(dim("  /exit — quit · /revert [runId] — undo the agent's file edits (latest run)"));
+      continue;
+    }
+    if (line.startsWith("/revert")) {
+      const runId = line.split(/\s+/)[1] ?? "";
+      await new Promise((res) => {
+        const p = spawn(
+          process.execPath,
+          [join(DIR, "gonext-local-worker.mjs"), "workspace", "revert", ...(runId ? [runId] : [])],
+          { stdio: "inherit" }
+        );
+        p.on("exit", res);
+        p.on("error", res);
+      });
+      continue;
+    }
+    history.push({ role: "user", content: line });
+    try {
+      const { payload } = await fetchAgentPayload(history);
+      const answer = await runAgentTurn(payload);
+      if (answer) {
+        history.push({ role: "assistant", content: answer });
+        console.log(`\n\n${answer}\n`);
+      } else {
+        history.pop(); // failed turn — don't poison the next request's history
+        console.log(red("\n(no answer — run failed or was aborted)\n"));
+      }
+    } catch (err) {
+      history.pop();
+      console.error(red(`\ngonext: ${err.message}\n`));
+    }
+  }
+  rl.close();
+  process.exit(0);
+}
+
+main();

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.172",
   "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",
@@ -13,7 +13,8 @@
     "url": "https://github.com/tiennsloit/gonext/issues"
   },
   "bin": {
-    "gonext-local-worker": "./gonext-local-worker.mjs"
+    "gonext-local-worker": "./gonext-local-worker.mjs",
+    "gonext": "./gonext-repl.mjs"
   },
   "scripts": {
     "deploy:local": "npm install -g .",
@@ -22,6 +23,7 @@
   },
   "files": [
     "gonext-local-worker.mjs",
+    "gonext-repl.mjs",
     "gonext_probe_agent.py",
     "gonext_agent_chat.py",
     "gonext_transcribe.py",