@tiens.nguyen/gonext-local-worker 1.0.47 → 1.0.48

package/README.md

@@ -1,3 +1,34 @@
 # @tiens.nguyen/gonext-local-worker
 Run:
   GONEXT_API_BASE=... GONEXT_WORKER_KEY=... npx -y --package @tiens.nguyen/gonext-local-worker gonext-local-worker
+
+## API Check / HTTP probe (Tools & Agents modes)
+
+The worker can run Postman-style HTTP probes queued from the web app
+("Tools" = `tool_only`, "Agents" = `agentic`). The worker always performs the
+actual HTTP request itself (Node `fetch`, so TLS works), measures the
+status/latency/headers/body, and classifies it (2xx/3xx/4xx/5xx/timeout/
+network_error).
+
+- **Tools (`tool_only`)** — no extra setup. The selected local model writes a
+  one-line health summary of the measured result.
+- **Agents (`agentic`)** — a [smolagents](https://github.com/huggingface/smolagents)
+  agent (running on the selected local model) produces the summary. Install it
+  in the worker's Python environment:
+
+  ```sh
+  pip install smolagents
+  ```
+
+  The agent talks to your local MLX OpenAI-compatible server (no cloud calls).
+  The agent only summarizes; the worker's measurement stays the source of truth,
+  so if smolagents or the model is unavailable the probe still returns the
+  measured result with a note.
+
+### Probe-related env
+
+  GONEXT_PROBE_PYTHON   Python executable for the smolagents agent
+                        (default: GONEXT_MLX_LM_PYTHON or python3)
+
+The agent script lives next to the worker as `gonext_probe_agent.py` (reads a
+JSON probe config on stdin, writes a JSON summary on stdout).

package/gonext-local-worker.mjs

@@ -8,14 +8,17 @@
  * - `gonext-local-worker` — starts polling loop (claims jobs and runs models)
  */
 import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
-import { execFile as execFileCallback } from "node:child_process";
+import { execFile as execFileCallback, spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { homedir, platform, tmpdir } from "node:os";
-import { extname, join } from "node:path";
+import { dirname, extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import dotenv from "dotenv";
 import OpenAI from "openai";
 
+const WORKER_DIR = dirname(fileURLToPath(import.meta.url));
+
 /** Avoid `node:child_process/promises` — not available on some Node builds / older runtimes. */
 const execFile = promisify(execFileCallback);
 
@@ -548,6 +551,298 @@ async function runChatJob(job) {
   }
 }
 
+function categorizeHttpStatus(status) {
+  if (status >= 200 && status < 300) return "2xx";
+  if (status >= 300 && status < 400) return "3xx";
+  if (status >= 400 && status < 500) return "4xx";
+  if (status >= 500 && status < 600) return "5xx";
+  return "network_error";
+}
+
+function probeVerdict(status, expectedStatus) {
+  if (expectedStatus === undefined || expectedStatus === null) {
+    return status >= 200 && status < 300 ? "pass" : "fail";
+  }
+  const list = Array.isArray(expectedStatus) ? expectedStatus : [expectedStatus];
+  return list.includes(status) ? "pass" : "fail";
+}
+
+/** tool_only / agentic summary: ask the selected model to interpret the measured result. */
+async function summarizeProbeWithModel(payload, result) {
+  const client = new OpenAI({
+    baseURL: payload.agentBaseURL,
+    apiKey: payload.agentApiKey || "local",
+    maxRetries: 0,
+    timeout: 60_000,
+  });
+  const lines = [
+    `HTTP probe result for ${result.request.method} ${result.request.url}`,
+  ];
+  if (result.response) {
+    lines.push(
+      `Status: ${result.response.status} ${result.response.statusText} (${result.category})`,
+      `Latency: ${result.response.latencyMs} ms`,
+      `Body (first chars): ${result.response.bodySnippet || "(empty)"}`
+    );
+  } else {
+    lines.push(`No response — ${result.category}: ${result.error ?? "unknown error"}`);
+  }
+  lines.push(
+    `Verdict: ${result.verdict}.`,
+    "In 1-2 sentences, say whether the endpoint is healthy and what this status means."
+  );
+  const completion = await client.chat.completions.create({
+    model: payload.agentModelId,
+    messages: [
+      {
+        role: "system",
+        content: "You are an API health assistant. Be concise and factual.",
+      },
+      { role: "user", content: lines.join("\n") },
+    ],
+    temperature: 0,
+    max_tokens: 200,
+  });
+  return completion.choices?.[0]?.message?.content?.trim() || "";
+}
+
+/** Deterministic HTTP measurement: real status/latency/headers/body, no model. */
+async function performHttpMeasurement(params) {
+  let response = null;
+  let category;
+  let errorMessage;
+  const reqStart = Date.now();
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), params.timeoutMs);
+  try {
+    const res = await fetch(params.url, {
+      method: params.method,
+      headers: params.headers,
+      body: params.sendBody ? params.body : undefined,
+      signal: ac.signal,
+      redirect: "manual",
+    });
+    const latencyMs = Date.now() - reqStart;
+    let text = "";
+    try {
+      text = await res.text();
+    } catch {
+      text = "";
+    }
+    const SNIP = 2048;
+    const bodySnippet =
+      text.length > SNIP
+        ? `${text.slice(0, SNIP)} …[truncated ${text.length - SNIP} chars]`
+        : text;
+    const resHeaders = {};
+    res.headers.forEach((v, k) => {
+      resHeaders[k] = v;
+    });
+    category = categorizeHttpStatus(res.status);
+    response = {
+      status: res.status,
+      statusText: res.statusText || "",
+      ok: res.status >= 200 && res.status < 300,
+      latencyMs,
+      headers: resHeaders,
+      bodySnippet,
+      bodyBytes: Buffer.byteLength(text),
+    };
+  } catch (err) {
+    const aborted =
+      ac.signal.aborted ||
+      (err && typeof err === "object" && err.name === "AbortError");
+    category = aborted ? "timeout" : "network_error";
+    errorMessage = aborted
+      ? `Request timed out after ${params.timeoutMs} ms`
+      : err instanceof Error
+      ? err.message
+      : String(err);
+  } finally {
+    clearTimeout(timer);
+  }
+  return { response, category, errorMessage };
+}
+
+/** Run a child process, feed it stdin, resolve with stdout (rejects on non-zero/timeout). */
+function runProcessWithStdin(cmd, cmdArgs, stdinStr, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, cmdArgs, { stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+    child.stdout.on("data", (d) => {
+      stdout += d;
+    });
+    child.stderr.on("data", (d) => {
+      stderr += d;
+    });
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      reject(e);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (timedOut) {
+        reject(new Error(`probe agent timed out after ${timeoutMs} ms`));
+        return;
+      }
+      if (code !== 0) {
+        reject(
+          new Error(
+            `probe agent exited ${code}${stderr.trim() ? `: ${stderr.trim().slice(0, 500)}` : ""}`
+          )
+        );
+        return;
+      }
+      resolve(stdout);
+    });
+    child.stdin.write(stdinStr);
+    child.stdin.end();
+  });
+}
+
+/**
+ * Agentic summary: drive a smolagents agent (on the selected local model) over
+ * the worker's measurement. The agent does not re-fetch — the worker's Node
+ * measurement stays the source of truth. Throws so callers can fall back.
+ */
+async function summarizeProbeAgentic(payload, result) {
+  const python =
+    (process.env.GONEXT_PROBE_PYTHON ?? process.env.GONEXT_MLX_LM_PYTHON ?? "")
+      .trim() || "python3";
+  const scriptPath = join(WORKER_DIR, "gonext_probe_agent.py");
+  const input = JSON.stringify({
+    request: result.request,
+    measurement: result.response,
+    category: result.category,
+    error: result.error ?? null,
+    agentBaseURL: payload?.agentBaseURL ?? "",
+    agentApiKey: payload?.agentApiKey ?? "",
+    agentModelId: payload?.agentModelId ?? "",
+  });
+  const timeoutMs =
+    (Number.isFinite(payload?.timeoutMs) ? payload.timeoutMs : 15_000) + 120_000;
+  const stdout = await runProcessWithStdin(python, [scriptPath], input, timeoutMs);
+  const parsed = JSON.parse(stdout);
+  const summary =
+    typeof parsed?.agentSummary === "string" ? parsed.agentSummary.trim() : "";
+  if (!summary) {
+    throw new Error(parsed?.error || "agent produced no summary");
+  }
+  return summary;
+}
+
+async function runHttpProbeJob(job) {
+  const { jobId, payload } = job;
+  const start = Date.now();
+  const runRes = await workerFetch(`/api/worker/jobs/${jobId}`, {
+    method: "PATCH",
+    body: JSON.stringify({ jobStatus: "running" }),
+  });
+  await ensureWorkerOk(runRes, `mark running http_probe jobId=${jobId}`);
+  try {
+    const method = String(payload?.method || "GET").toUpperCase();
+    const url = String(payload?.url || "");
+    if (!url) throw new Error("http_probe payload missing url.");
+    const headers =
+      payload?.headers && typeof payload.headers === "object" ? payload.headers : {};
+    const sendBody =
+      !["GET", "HEAD"].includes(method) &&
+      typeof payload?.body === "string" &&
+      payload.body.length > 0;
+    const timeoutMs =
+      Number.isFinite(payload?.timeoutMs) && payload.timeoutMs > 0
+        ? payload.timeoutMs
+        : 15_000;
+    const requestBodyBytes = sendBody ? Buffer.byteLength(payload.body) : 0;
+    const measureParams = { method, url, headers, sendBody, body: payload?.body, timeoutMs };
+    const agentMode = payload?.agentMode === "agentic" ? "agentic" : "tool_only";
+
+    // The worker's Node fetch is the authoritative measurement for both modes.
+    const measurement = await performHttpMeasurement(measureParams);
+    const { response, category, errorMessage } = measurement;
+
+    const status = response?.status ?? 0;
+    const verdict =
+      category === "timeout" || category === "network_error"
+        ? "fail"
+        : probeVerdict(status, payload?.expectedStatus);
+
+    const result = {
+      request: { method, url, headers, bodyBytes: requestBodyBytes },
+      response,
+      category,
+      verdict,
+      agentMode,
+      agentModel: payload?.agentModel || payload?.agentModelId || "",
+      ...(errorMessage ? { error: errorMessage } : {}),
+    };
+
+    if (agentMode === "agentic") {
+      try {
+        result.agentSummary = await summarizeProbeAgentic(payload, result);
+      } catch (e) {
+        // smolagents/Python unavailable: fall back to a direct model summary.
+        try {
+          result.agentSummary = `${await summarizeProbeWithModel(payload, result)} (agentic fallback)`;
+        } catch {
+          result.agentSummary = `(Agentic summary unavailable: ${
+            e instanceof Error ? e.message : String(e)
+          })`;
+        }
+      }
+    } else {
+      try {
+        result.agentSummary = await summarizeProbeWithModel(payload, result);
+      } catch (e) {
+        result.agentSummary = `(Model summary unavailable: ${
+          e instanceof Error ? e.message : String(e)
+        })`;
+      }
+    }
+
+    const totalTimeSeconds = (Date.now() - start) / 1000;
+    const doneRes = await workerFetch(`/api/worker/jobs/${jobId}`, {
+      method: "PATCH",
+      body: JSON.stringify({
+        jobStatus: "completed",
+        resultText: JSON.stringify(result),
+        tokenCount: 1,
+        totalTimeSeconds,
+      }),
+    });
+    await ensureWorkerOk(doneRes, `complete http_probe jobId=${jobId}`);
+    console.log(
+      `[gonext-worker] completed http_probe ${jobId} (${totalTimeSeconds.toFixed(
+        1
+      )}s) ${method} ${url} -> ${category}/${verdict}`
+    );
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    const failRes = await workerFetch(`/api/worker/jobs/${jobId}`, {
+      method: "PATCH",
+      body: JSON.stringify({
+        jobStatus: "failed",
+        errorMessage: message,
+        totalTimeSeconds: (Date.now() - start) / 1000,
+      }),
+    });
+    if (!failRes.ok) {
+      const snippet = (await failRes.text().catch(() => "")).trim().slice(0, 500);
+      console.error(
+        `[gonext-worker] http_probe fail PATCH also failed ${failRes.status} jobId=${jobId}` +
+          (snippet ? ` response=${snippet}` : "")
+      );
+    }
+    console.error(`[gonext-worker] failed http_probe ${jobId}:`, message);
+  }
+}
+
 function resolveImageExtension(mimeType, fileName) {
   const byMime = {
     "image/png": ".png",
@@ -1224,6 +1519,10 @@ async function pollOnce() {
       );
       continue;
     }
+    if (job.jobType === "http_probe") {
+      await runHttpProbeJob(job);
+      return;
+    }
     const isOcrByType = job.jobType === "ocr";
     const isOcrByPayload =
       job.payload &&

package/gonext_probe_agent.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""
+gonext probe agent (agentic mode for the gonext local worker).
+
+Reads a JSON probe config on stdin and writes a single JSON object on stdout:
+
+  in:  {"request": {"method","url"},
+        "measurement": {"status","statusText","latencyMs","headers",
+                        "bodySnippet","bodyBytes"} | null,
+        "category": str, "error": str | null,
+        "agentBaseURL","agentApiKey","agentModelId"}
+  out: {"agentSummary": str, "error": str | null}
+
+The worker performs the authoritative HTTP measurement (reliable TLS via Node
+fetch) and passes it here; this script drives a smolagents agent on the selected
+local model to produce the natural-language health assessment. The agent's
+`send_request` tool returns the already-measured result, so there is exactly one
+network call (the worker's) and the measured status stays the source of truth.
+
+smolagents/rich writes its console UI to stdout, so we redirect stdout to stderr
+during the agent run and only emit our JSON result on stdout.
+
+See docs/plans/smolagents-local-worker-http-probe.md.
+"""
+import contextlib
+import json
+import sys
+
+
+def describe(measurement, category, error):
+    if not measurement or error:
+        return f"The request did not get a response ({category}): {error or 'unknown error'}."
+    return (
+        f"HTTP {measurement.get('status')} {measurement.get('statusText', '')} "
+        f"({category}) in {measurement.get('latencyMs')} ms. "
+        f"Body preview: {str(measurement.get('bodySnippet', ''))[:400]}"
+    )
+
+
+def run_agent_summary(cfg):
+    """Returns (summary, error). Never raises."""
+    try:
+        from smolagents import CodeAgent, OpenAIServerModel, tool
+    except Exception as e:  # noqa: BLE001
+        return "", f"smolagents not installed ({e})"
+
+    request = cfg.get("request") or {}
+    method = (request.get("method") or "GET").upper()
+    url = request.get("url") or ""
+    measurement = cfg.get("measurement")
+    category = cfg.get("category") or ""
+    error = cfg.get("error")
+    measured_text = describe(measurement, category, error)
+
+    @tool
+    def send_request() -> str:
+        """Send the configured HTTP request to the target endpoint and return its
+        status code and a short body preview."""
+        return measured_text
+
+    try:
+        model = OpenAIServerModel(
+            model_id=cfg.get("agentModelId") or "",
+            api_base=cfg.get("agentBaseURL") or "",
+            api_key=cfg.get("agentApiKey") or "local",
+        )
+        agent = CodeAgent(tools=[send_request], model=model, max_steps=4)
+        task = (
+            f"Use send_request to call {method} {url}. Then report the HTTP status "
+            "code, classify it (2xx success, 3xx redirect, 4xx client error, 5xx "
+            "server error, or network failure), and give a one-sentence health "
+            "assessment of the endpoint."
+        )
+        # smolagents/rich logs to stdout; keep stdout clean for our JSON result.
+        with contextlib.redirect_stdout(sys.stderr):
+            summary = str(agent.run(task)).strip()
+        return summary, None
+    except Exception as e:  # noqa: BLE001
+        return "", f"agent run failed ({e})"
+
+
+def main():
+    try:
+        cfg = json.load(sys.stdin)
+    except Exception as e:  # noqa: BLE001
+        json.dump({"agentSummary": "", "error": f"invalid input: {e}"}, sys.stdout)
+        return
+    summary, agent_error = run_agent_summary(cfg)
+    json.dump({"agentSummary": summary, "error": agent_error}, sys.stdout)
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gonext-local-worker",
-  "version": "1.0.47",
+  "version": "1.0.48",
   "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",
@@ -22,6 +22,7 @@
   },
   "files": [
     "gonext-local-worker.mjs",
+    "gonext_probe_agent.py",
     "README.md",
     "launchd/"
   ],