@tiens.nguyen/gonext-local-worker 1.0.0

package/README.md

@@ -0,0 +1,79 @@
+# gonext-local-worker
+
+Runs on **your Mac** next to **Ollama** or any **OpenAI-compatible** local server. It:
+
+1. Polls **`POST /api/worker/jobs/next`** on your GoNext cloud API (Lambda).
+2. Runs the job against **`payload.baseURL`** (your LAN `http://127.0.0.1:11434/v1` etc.).
+3. **`PATCH`**es **`running`** → **`completed`** / **`failed`** so DynamoDB and the web app update.
+
+You must create a **Worker API key** in the web app **Settings** (stored as a hash in DynamoDB).
+
+## Install
+
+```bash
+npm install -g @gomarsic/gonext-local-worker
+```
+
+Or from source:
+
+```bash
+cd tools/gonext-local-worker
+npm install
+npm link
+```
+
+Requires **Node.js 18+**.
+
+## Configure
+
+Create `~/.gonext/worker.env` (optional):
+
+```bash
+mkdir -p ~/.gonext
+cat > ~/.gonext/worker.env << 'EOF'
+GONEXT_API_BASE=https://YOUR_API.execute-api.ap-southeast-1.amazonaws.com
+GONEXT_WORKER_KEY=paste-your-worker-secret-here
+GONEXT_POLL_MS=1500
+EOF
+chmod 600 ~/.gonext/worker.env
+```
+
+Or export in the shell:
+
+```bash
+export GONEXT_API_BASE=https://....execute-api....amazonaws.com
+export GONEXT_WORKER_KEY=...
+```
+
+## Run
+
+```bash
+gonext-local-worker
+```
+
+Options:
+
+```bash
+gonext-local-worker --poll-ms 2000
+gonext-local-worker --api-base https://other-host.example
+gonext-local-worker --help
+```
+
+Leave this process **running** while you use async local models from the web app.
+
+## Run at login (macOS LaunchAgent)
+
+1. Copy `launchd/com.gonext.worker.plist.example` to `~/Library/LaunchAgents/com.gonext.worker.plist`.
+2. Edit paths: set **full path** to `gonext-local-worker` (`which gonext-local-worker` after `npm link`).
+3. `launchctl load ~/Library/LaunchAgents/com.gonext.worker.plist`
+
+Unload:
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.gonext.worker.plist
+```
+
+## Troubleshooting
+
+- **`403` / invalid key** — Regenerate worker key in Settings and update `GONEXT_WORKER_KEY`.
+- **Job never claimed** — Ensure DynamoDB + worker routes work; Settings must include **Ollama base URL** so the queued payload points at a reachable host from this Mac (`127.0.0.1` is fine).

package/gonext-local-worker.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+/**
+ * GoNext local LLM worker — runs on the Mac where Ollama / MLX HTTP server lives.
+ * Polls your cloud API for jobs, calls the model locally, PATCHes status back.
+ *
+ * Env:
+ *   GONEXT_API_BASE   HTTPS origin only (no trailing slash), e.g. https://xxx.execute-api....amazonaws.com
+ *   GONEXT_WORKER_KEY Plaintext worker secret from Web → Settings → Worker API key
+ *   GONEXT_POLL_MS    Poll interval when idle (default 1500)
+ *
+ * Optional env files (loaded in order; shell exports win if set before launch):
+ *   ~/.gonext/worker.env
+ *   ./.env (cwd)
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import dotenv from "dotenv";
+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 };
+  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];
+  }
+  return out;
+}
+
+function printHelp() {
+  console.log(`
+gonext-local-worker — bridge cloud GoNext jobs ↔ local LLM (Ollama / OpenAI-compatible)
+
+Usage:
+  export GONEXT_API_BASE=https://....amazonaws.com
+  export GONEXT_WORKER_KEY=your-secret-from-settings
+  gonext-local-worker
+
+Options:
+  --poll-ms <ms>    Idle poll interval (default 1500 or GONEXT_POLL_MS)
+  --api-base <url>  Override GONEXT_API_BASE
+
+Config files (optional):
+  ~/.gonext/worker.env
+  .env in current directory
+
+Install (from repo):
+  cd tools/gonext-local-worker && npm install && npm link
+
+Then keep this running while you use the web app with local models.
+`);
+}
+
+const args = parseArgs(process.argv);
+if (args.help) {
+  printHelp();
+  process.exit(0);
+}
+
+const apiBase = (
+  args.apiBase ??
+  process.env.GONEXT_API_BASE ??
+  ""
+).replace(/\/+$/, "");
+const workerKey = process.env.GONEXT_WORKER_KEY ?? "";
+const pollMs =
+  (Number.isFinite(args.pollMs) && args.pollMs > 0
+    ? args.pollMs
+    : Number(process.env.GONEXT_POLL_MS ?? "1500")) || 1500;
+
+if (!apiBase || !workerKey) {
+  console.error(
+    "Missing GONEXT_API_BASE or GONEXT_WORKER_KEY.\nSet them or put them in ~/.gonext/worker.env — run with --help."
+  );
+  process.exit(1);
+}
+
+function ts() {
+  return new Date().toISOString();
+}
+
+function toOpenAIMessages(messages) {
+  return messages.map((m) => {
+    if (m.role === "user" && m.attachments?.length) {
+      return {
+        role: m.role,
+        content: [
+          { type: "text", text: m.content },
+          ...m.attachments.map((a) => ({
+            type: "image_url",
+            image_url: { url: `data:${a.mimeType};base64,${a.data}` },
+          })),
+        ],
+      };
+    }
+    return { role: m.role, content: m.content };
+  });
+}
+
+async function workerFetch(path, init = {}) {
+  const url = `${apiBase}${path.startsWith("/") ? path : `/${path}`}`;
+  const headers = {
+    "Content-Type": "application/json",
+    "X-Worker-Key": workerKey,
+    ...(init.headers ?? {}),
+  };
+  return fetch(url, { ...init, headers });
+}
+
+let shuttingDown = false;
+
+async function runChatJob(job) {
+  const { jobId, payload } = job;
+  const start = Date.now();
+  const patchRunning = await workerFetch(`/api/worker/jobs/${jobId}`, {
+    method: "PATCH",
+    body: JSON.stringify({ jobStatus: "running" }),
+  });
+  if (!patchRunning.ok) {
+    const t = await patchRunning.text().catch(() => "");
+    console.error(`[${ts()}] PATCH running failed ${patchRunning.status}`, t);
+    return;
+  }
+
+  const client = new OpenAI({
+    baseURL: payload.baseURL,
+    apiKey: payload.apiKey || "ollama",
+  });
+
+  try {
+    const completion = await client.chat.completions.create({
+      model: payload.modelId,
+      messages: toOpenAIMessages(payload.messages),
+      temperature: 0,
+    });
+    const text = completion.choices[0]?.message?.content ?? "";
+    const totalTimeSeconds = (Date.now() - start) / 1000;
+    await workerFetch(`/api/worker/jobs/${jobId}`, {
+      method: "PATCH",
+      body: JSON.stringify({
+        jobStatus: "completed",
+        resultText: text,
+        tokenCount: Math.max(1, completion.usage?.total_tokens ?? 1),
+        totalTimeSeconds,
+      }),
+    });
+    console.log(
+      `[${ts()}] completed job ${jobId} (${totalTimeSeconds.toFixed(1)}s)`
+    );
+  } catch (e) {
+    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,
+      }),
+    });
+    console.error(`[${ts()}] failed job ${jobId}:`, message);
+  }
+}
+
+async function pollOnce() {
+  const res = await workerFetch("/api/worker/jobs/next", { method: "POST" });
+  if (res.status === 204) return;
+  if (!res.ok) {
+    const t = await res.text().catch(() => "");
+    throw new Error(`POST /api/worker/jobs/next → ${res.status}: ${t}`);
+  }
+  const job = await res.json();
+  if (job?.jobId && job.payload) {
+    await runChatJob(job);
+  }
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function main() {
+  console.log(`[${ts()}] gonext-local-worker`);
+  console.log(`  API   ${apiBase}`);
+  console.log(`  poll  every ${pollMs}ms (idle)`);
+  console.log(`  stop  Ctrl+C`);
+
+  const loop = async () => {
+    while (!shuttingDown) {
+      try {
+        await pollOnce();
+      } catch (e) {
+        console.error(`[${ts()}] poll error:`, e instanceof Error ? e.message : e);
+      }
+      if (shuttingDown) break;
+      await sleep(pollMs);
+    }
+  };
+
+  const stop = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    console.log(`\n[${ts()}] shutting down…`);
+    process.exit(0);
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+
+  await loop();
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/launchd/com.gonext.worker.plist.example

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.gonext.worker</string>
+  <key>ProgramArguments</key>
+  <array>
+    <!-- Replace with output of: which gonext-local-worker -->
+    <string>/usr/local/bin/gonext-local-worker</string>
+  </array>
+  <!-- Optional: uncomment to force Node path -->
+  <!--
+  <array>
+    <string>/usr/local/bin/node</string>
+    <string>/ABSOLUTE/PATH/TO/gonext/tools/gonext-local-worker/gonext-local-worker.mjs</string>
+  </array>
+  -->
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>/tmp/gonext-worker.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/gonext-worker.err</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <!-- Or rely on ~/.gonext/worker.env (loaded by the worker) -->
+    <key>PATH</key>
+    <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin</string>
+  </dict>
+</dict>
+</plist>

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@tiens.nguyen/gonext-local-worker",
+  "version": "1.0.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tiennsloit/gonext.git"
+  },
+  "homepage": "https://github.com/tiennsloit/gonext#readme",
+  "bugs": {
+    "url": "https://github.com/tiennsloit/gonext/issues"
+  },
+  "bin": {
+    "gonext-local-worker": "./gonext-local-worker.mjs"
+  },
+  "files": [
+    "gonext-local-worker.mjs",
+    "README.md",
+    "launchd/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "openai": "^4.77.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}