@tiens.nguyen/gonext-local-worker 1.0.0 → 1.0.3

package/README.md

@@ -11,7 +11,7 @@ You must create a **Worker API key** in the web app **Settings** (stored as a ha
 ## Install
 
 ```bash
-npm install -g @gomarsic/gonext-local-worker
+npm install -g @tiens.nguyen/gonext-local-worker
 ```
 
 Or from source:
@@ -56,11 +56,52 @@ Options:
 ```bash
 gonext-local-worker --poll-ms 2000
 gonext-local-worker --api-base https://other-host.example
+gonext-local-worker --mode webhook --webhook-port 5001
+gonext-local-worker --mode both
 gonext-local-worker --help
 ```
 
 Leave this process **running** while you use async local models from the web app.
 
+## Push-dispatch mode (new option)
+
+You now have 2 ways to update job status:
+
+1. **Polling mode** (existing): worker polls `/api/worker/jobs/next`.
+2. **Webhook mode** (new): API push-dispatches job payloads to your local worker endpoint.
+
+Run local webhook endpoint:
+
+```bash
+gonext-local-worker --mode webhook --webhook-port 5001
+```
+
+or keep both (recommended transition):
+
+```bash
+gonext-local-worker --mode both --webhook-port 5001
+```
+
+Expose webhook with ngrok:
+
+```bash
+ngrok http 5001
+```
+
+Then in web app Settings set **Worker webhook URL** to:
+
+`https://<your-ngrok-domain>/api/dispatch-job`
+
+Local worker API endpoints on port 5001:
+
+- `POST /api/chat` -> proxies to `http://localhost:11434/api/chat`
+- `POST /api/generate` -> proxies to `http://localhost:11434/api/generate`
+- `GET /api/tags` -> proxies to `http://localhost:11434/api/tags`
+- `POST /api/dispatch-job` -> cloud dispatch entrypoint (token-protected)
+- `GET /api/health`
+
+Legacy non-prefixed routes (`/chat`, `/generate`, `/tags`, `/dispatch-job`, `/health`) are also available for compatibility.
+
 ## Run at login (macOS LaunchAgent)
 
 1. Copy `launchd/com.gonext.worker.plist.example` to `~/Library/LaunchAgents/com.gonext.worker.plist`.

package/gonext-local-worker.mjs

@@ -13,21 +13,33 @@
  *   ./.env (cwd)
  */
 import { homedir } from "node:os";
+import os from "node:os";
+import { createHash } from "node:crypto";
 import { join } from "node:path";
 import dotenv from "dotenv";
+import express from "express";
 import OpenAI from "openai";
 
 dotenv.config({ path: join(homedir(), ".gonext", "worker.env") });
 dotenv.config();
 
 function parseArgs(argv) {
-  const out = { help: false, pollMs: undefined, apiBase: undefined };
+  const out = {
+    help: false,
+    pollMs: undefined,
+    apiBase: undefined,
+    mode: undefined,
+    webhookPort: undefined,
+  };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--help" || a === "-h") out.help = true;
     else if (a === "--poll-ms" && argv[i + 1])
       out.pollMs = Number(argv[++i]);
     else if (a === "--api-base" && argv[i + 1]) out.apiBase = argv[++i];
+    else if (a === "--mode" && argv[i + 1]) out.mode = argv[++i];
+    else if (a === "--webhook-port" && argv[i + 1])
+      out.webhookPort = Number(argv[++i]);
   }
   return out;
 }
@@ -44,13 +56,15 @@ Usage:
 Options:
   --poll-ms <ms>    Idle poll interval (default 1500 or GONEXT_POLL_MS)
   --api-base <url>  Override GONEXT_API_BASE
+  --mode <poll|webhook|both>  Worker mode (default: poll)
+  --webhook-port <n>          Local webhook port (default: 5001)
 
 Config files (optional):
   ~/.gonext/worker.env
   .env in current directory
 
-Install (from repo):
-  cd tools/gonext-local-worker && npm install && npm link
+Install:
+  npm install -g @tiens.nguyen/gonext-local-worker
 
 Then keep this running while you use the web app with local models.
 `);
@@ -72,6 +86,17 @@ const pollMs =
   (Number.isFinite(args.pollMs) && args.pollMs > 0
     ? args.pollMs
     : Number(process.env.GONEXT_POLL_MS ?? "1500")) || 1500;
+const modeRaw = String(args.mode ?? process.env.GONEXT_WORKER_MODE ?? "poll");
+const mode = ["poll", "webhook", "both"].includes(modeRaw)
+  ? modeRaw
+  : "poll";
+const webhookPort =
+  (Number.isFinite(args.webhookPort) && args.webhookPort > 0
+    ? args.webhookPort
+    : Number(process.env.GONEXT_WEBHOOK_PORT ?? "5001")) || 5001;
+const ollamaBase = (
+  process.env.GONEXT_LOCAL_OLLAMA_BASE ?? "http://127.0.0.1:11434"
+).replace(/\/+$/, "");
 
 if (!apiBase || !workerKey) {
   console.error(
@@ -80,6 +105,12 @@ if (!apiBase || !workerKey) {
   process.exit(1);
 }
 
+const WORKER_VERSION = "1.0.0";
+const WORKER_HOST = os.hostname();
+const DISPATCH_TOKEN = createHash("sha256")
+  .update(workerKey, "utf8")
+  .digest("hex");
+
 function ts() {
   return new Date().toISOString();
 }
@@ -113,10 +144,31 @@ async function workerFetch(path, init = {}) {
 }
 
 let shuttingDown = false;
+let activeJobId = "";
+let lastError = "";
+let webhookServer = null;
+
+async function postHeartbeat(payload) {
+  try {
+    await workerFetch("/api/worker/heartbeat", {
+      method: "POST",
+      body: JSON.stringify({
+        workerVersion: WORKER_VERSION,
+        host: WORKER_HOST,
+        ...payload,
+      }),
+    });
+  } catch {
+    /* keep worker loop alive */
+  }
+}
 
 async function runChatJob(job) {
   const { jobId, payload } = job;
   const start = Date.now();
+  activeJobId = jobId;
+  lastError = "";
+  await postHeartbeat({ state: "running", currentJobId: jobId });
   const patchRunning = await workerFetch(`/api/worker/jobs/${jobId}`, {
     method: "PATCH",
     body: JSON.stringify({ jobStatus: "running" }),
@@ -124,6 +176,13 @@ async function runChatJob(job) {
   if (!patchRunning.ok) {
     const t = await patchRunning.text().catch(() => "");
     console.error(`[${ts()}] PATCH running failed ${patchRunning.status}`, t);
+    await postHeartbeat({
+      state: "error",
+      currentJobId: jobId,
+      lastError: `PATCH running failed ${patchRunning.status}`,
+    });
+    lastError = `PATCH running failed ${patchRunning.status}`;
+    activeJobId = "";
     return;
   }
 
@@ -152,6 +211,12 @@ async function runChatJob(job) {
     console.log(
       `[${ts()}] completed job ${jobId} (${totalTimeSeconds.toFixed(1)}s)`
     );
+    await postHeartbeat({
+      state: "idle",
+      currentJobId: "",
+      lastJobCompletedAt: new Date().toISOString(),
+    });
+    activeJobId = "";
   } catch (e) {
     const message = e instanceof Error ? e.message : String(e);
     await workerFetch(`/api/worker/jobs/${jobId}`, {
@@ -163,6 +228,13 @@ async function runChatJob(job) {
       }),
     });
     console.error(`[${ts()}] failed job ${jobId}:`, message);
+    await postHeartbeat({
+      state: "error",
+      currentJobId: jobId,
+      lastError: message,
+    });
+    lastError = message;
+    activeJobId = "";
   }
 }
 
@@ -183,18 +255,240 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 
+function requireDispatchToken(req, res) {
+  const token = req.header("x-gonext-dispatch-token") ?? "";
+  if (token !== DISPATCH_TOKEN) {
+    res.status(403).json({ error: "Invalid dispatch token." });
+    return false;
+  }
+  return true;
+}
+
+function toOllamaChatMessages(messages) {
+  return (messages ?? []).map((m) => ({
+    role: m.role,
+    content: m.content,
+    ...(Array.isArray(m.attachments) && m.attachments.length > 0
+      ? { images: m.attachments.map((a) => a.data) }
+      : {}),
+  }));
+}
+
+async function runOllamaAndMaybeUpdateJob(params) {
+  const { endpoint, requestBody, jobId, extractResultText } = params;
+  const hasJob = typeof jobId === "string" && jobId.length > 0;
+  const start = Date.now();
+  if (hasJob) {
+    activeJobId = jobId;
+    lastError = "";
+    await postHeartbeat({ state: "running", currentJobId: jobId });
+    await workerFetch(`/api/worker/jobs/${jobId}`, {
+      method: "PATCH",
+      body: JSON.stringify({ jobStatus: "running" }),
+    });
+  }
+  try {
+    const res = await fetch(`${ollamaBase}${endpoint}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        stream: false,
+        ...requestBody,
+      }),
+    });
+    const raw = await res.text();
+    if (!res.ok) {
+      throw new Error(`Ollama ${endpoint} failed ${res.status}: ${raw}`);
+    }
+    const parsed = raw ? JSON.parse(raw) : {};
+    if (hasJob) {
+      await workerFetch(`/api/worker/jobs/${jobId}`, {
+        method: "PATCH",
+        body: JSON.stringify({
+          jobStatus: "completed",
+          resultText: extractResultText(parsed),
+          tokenCount: 1,
+          totalTimeSeconds: (Date.now() - start) / 1000,
+        }),
+      });
+      await postHeartbeat({
+        state: "idle",
+        currentJobId: "",
+        lastJobCompletedAt: new Date().toISOString(),
+      });
+      activeJobId = "";
+    }
+    return parsed;
+  } catch (e) {
+    if (hasJob) {
+      const message = e instanceof Error ? e.message : String(e);
+      await workerFetch(`/api/worker/jobs/${jobId}`, {
+        method: "PATCH",
+        body: JSON.stringify({
+          jobStatus: "failed",
+          errorMessage: message,
+          totalTimeSeconds: (Date.now() - start) / 1000,
+        }),
+      });
+      await postHeartbeat({
+        state: "error",
+        currentJobId: jobId,
+        lastError: message,
+      });
+      lastError = message;
+      activeJobId = "";
+    }
+    throw e;
+  }
+}
+
+function startWebhookServer() {
+  const app = express();
+  app.use(express.json({ limit: "10mb" }));
+
+  const healthHandler = (_req, res) => {
+    const state =
+      activeJobId.length > 0 ? "running" : lastError ? "error" : "idle";
+    res.json({
+      ok: true,
+      workerVersion: WORKER_VERSION,
+      host: WORKER_HOST,
+      mode,
+      state,
+      activeJobId: activeJobId || undefined,
+      lastError: lastError || undefined,
+      dispatchPath: "/dispatch-job",
+      chatPath: "/chat",
+      generatePath: "/generate",
+      tagsPath: "/tags",
+      ollamaBase,
+    });
+  };
+  app.get("/health", healthHandler);
+  app.get("/api/health", healthHandler);
+
+  const tagsHandler = async (_req, res) => {
+    try {
+      const r = await fetch(`${ollamaBase}/api/tags`, { method: "GET" });
+      const raw = await r.text();
+      if (!r.ok) {
+        res
+          .status(r.status)
+          .json({ error: `Ollama /api/tags failed ${r.status}`, raw });
+        return;
+      }
+      res.type("application/json").send(raw || "{}");
+    } catch (e) {
+      res.status(500).json({ error: e instanceof Error ? e.message : "error" });
+    }
+  };
+  app.get("/tags", tagsHandler);
+  app.get("/api/tags", tagsHandler);
+
+  const dispatchJobHandler = async (req, res) => {
+    if (!requireDispatchToken(req, res)) return;
+    const body = req.body ?? {};
+    if (!body?.jobId || !body?.payload) {
+      res.status(400).json({ error: "Expected { jobId, payload }." });
+      return;
+    }
+    if (activeJobId) {
+      res.status(409).json({ error: "Worker busy.", activeJobId });
+      return;
+    }
+    const payload = body.payload;
+    const chatBody = {
+      model: payload.modelId,
+      messages: toOllamaChatMessages(payload.messages),
+    };
+    void runOllamaAndMaybeUpdateJob({
+      endpoint: "/api/chat",
+      requestBody: chatBody,
+      jobId: String(body.jobId),
+      extractResultText: (j) => j?.message?.content ?? "",
+    }).catch((e) => {
+      console.error("[dispatch-job] error:", e instanceof Error ? e.message : e);
+    });
+    res.status(202).json({ ok: true, accepted: true, jobId: body.jobId });
+  };
+  app.post("/dispatch-job", dispatchJobHandler);
+  app.post("/api/dispatch-job", dispatchJobHandler);
+
+  const chatHandler = async (req, res) => {
+    try {
+      const body = req.body ?? {};
+      const jobId = typeof body.jobId === "string" ? body.jobId : "";
+      if (jobId && !requireDispatchToken(req, res)) return;
+      const requestBody =
+        body.request && typeof body.request === "object" ? body.request : body;
+      const parsed = await runOllamaAndMaybeUpdateJob({
+        endpoint: "/api/chat",
+        requestBody,
+        jobId,
+        extractResultText: (j) => j?.message?.content ?? "",
+      });
+      res.json(parsed);
+    } catch (e) {
+      res.status(500).json({ error: e instanceof Error ? e.message : "error" });
+    }
+  };
+  app.post("/chat", chatHandler);
+  app.post("/api/chat", chatHandler);
+
+  const generateHandler = async (req, res) => {
+    try {
+      const body = req.body ?? {};
+      const jobId = typeof body.jobId === "string" ? body.jobId : "";
+      if (jobId && !requireDispatchToken(req, res)) return;
+      const requestBody =
+        body.request && typeof body.request === "object" ? body.request : body;
+      const parsed = await runOllamaAndMaybeUpdateJob({
+        endpoint: "/api/generate",
+        requestBody,
+        jobId,
+        extractResultText: (j) => j?.response ?? "",
+      });
+      res.json(parsed);
+    } catch (e) {
+      res.status(500).json({ error: e instanceof Error ? e.message : "error" });
+    }
+  };
+  app.post("/generate", generateHandler);
+  app.post("/api/generate", generateHandler);
+
+  webhookServer = app.listen(webhookPort, "127.0.0.1", () => {
+    console.log(
+      `[${ts()}] local worker API on http://127.0.0.1:${webhookPort} (/chat, /generate, /tags, /dispatch-job, /health)`
+    );
+    console.log(`[${ts()}] dispatch token is SHA256(worker key)`);
+  });
+}
+
 async function main() {
   console.log(`[${ts()}] gonext-local-worker`);
   console.log(`  API   ${apiBase}`);
-  console.log(`  poll  every ${pollMs}ms (idle)`);
+  console.log(`  mode  ${mode}`);
+  if (mode === "poll" || mode === "both") {
+    console.log(`  poll  every ${pollMs}ms (idle)`);
+  }
+  if (mode === "webhook" || mode === "both") {
+    console.log(`  hook  http://127.0.0.1:${webhookPort}/dispatch-job`);
+  }
   console.log(`  stop  Ctrl+C`);
+  await postHeartbeat({ state: "idle", currentJobId: "" });
 
   const loop = async () => {
     while (!shuttingDown) {
       try {
         await pollOnce();
+        await postHeartbeat({ state: "idle", currentJobId: "" });
       } catch (e) {
         console.error(`[${ts()}] poll error:`, e instanceof Error ? e.message : e);
+        await postHeartbeat({
+          state: "error",
+          currentJobId: "",
+          lastError: e instanceof Error ? e.message : String(e),
+        });
       }
       if (shuttingDown) break;
       await sleep(pollMs);
@@ -205,12 +499,22 @@ async function main() {
     if (shuttingDown) return;
     shuttingDown = true;
     console.log(`\n[${ts()}] shutting down…`);
+    if (webhookServer) {
+      webhookServer.close();
+    }
     process.exit(0);
   };
   process.on("SIGINT", stop);
   process.on("SIGTERM", stop);
 
-  await loop();
+  if (mode === "webhook" || mode === "both") {
+    startWebhookServer();
+  }
+  if (mode === "poll" || mode === "both") {
+    await loop();
+  } else {
+    await new Promise(() => {});
+  }
 }
 
 main().catch((e) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gonext-local-worker",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "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 @@
   },
   "dependencies": {
     "dotenv": "^16.4.5",
+    "express": "^4.21.0",
     "openai": "^4.77.0"
   },
   "engines": {