jev-gateway 0.1.0 → 0.2.0

package/bin/launcher.mjs

@@ -35,19 +35,23 @@ export async function runLauncher(spec) {
   const logFile = join(STATE_DIR, `${spec.client}.log`);
   const pidFile = join(STATE_DIR, `${spec.client}.pid`);
 
-  const help = `${spec.name} — ${spec.client} with tool selection routed through Jev
+  const help = `${spec.name}: ${spec.client} with tool selection routed through Jev
 
-  ${spec.name} [${spec.client} args…]   start the router if needed, then run ${spec.client} through it
-  ${spec.name} --jev-start     only start the background router
-  ${spec.name} --jev-status    is the router up, and where does it forward to?
-  ${spec.name} --jev-logs      follow the router's decisions (run in a second terminal)
-  ${spec.name} --jev-stop      stop the background router
-  ${spec.name} --jev-config    how to point plain \`${spec.client}\` at the router permanently
+  ${spec.name} [${spec.client} args]    start the gateway if needed, then run ${spec.client} through it
+  ${spec.name} --dashboard        open the monitoring dashboard in your browser
+  ${spec.name} --routing on|off   off = baseline mode: stop asking Jev, keep counting tokens
+  ${spec.name} --status           is the gateway running, and where does it forward to?
+  ${spec.name} --logs             follow routing decisions live (use a second terminal)
+  ${spec.name} --start            start the gateway without opening ${spec.client}
+  ${spec.name} --stop             stop the background gateway
+  ${spec.name} --print-config     how to point plain \`${spec.client}\` at the gateway permanently
+  ${spec.name} --gateway-help     this text (\`--help\` shows ${spec.client}'s own help)
 
 Environment (or ${ENV_FILES.at(-1)}):
   TYPESAFE_API_KEY   required — Jev makes the tool-selection call
   ${spec.portEnv}   router port for ${spec.client} (default ${spec.defaultPort})
   ${spec.upstreamHelp}
+  BROWSER            command --dashboard opens the page with; "none" only prints the URL
 `;
 
   const health = async () => {
@@ -68,7 +72,7 @@ Environment (or ${ENV_FILES.at(-1)}):
     if (running) {
       if (running.upstream === upstream) return;
       console.error(`${spec.name}: router on :${port} forwards to ${running.upstream}, expected ${upstream}.`);
-      console.error(`${" ".repeat(spec.name.length)}  Run \`${spec.name} --jev-stop\` and try again.`);
+      console.error(`${" ".repeat(spec.name.length)}  Run \`${spec.name} --stop\` and try again.`);
       process.exit(1);
     }
     if (!process.env.TYPESAFE_API_KEY) {
@@ -82,7 +86,8 @@ Environment (or ${ENV_FILES.at(-1)}):
     const { UPSTREAM_API_KEY: _key, ROUTER_API_KEY: _routerKey, ...env } = process.env;
     const child = spawn(process.execPath, ROUTER_ARGS, {
       cwd: ROOT,
-      env: { ...env, PORT: String(port), UPSTREAM_BASE_URL: upstream },
+      // JEV_LOG_FILE is where stdout goes (below): the router replays it so the dashboard keeps its history.
+      env: { ...env, PORT: String(port), UPSTREAM_BASE_URL: upstream, JEV_CLIENT: spec.client, JEV_LOG_FILE: logFile },
       detached: true,
       stdio: ["ignore", log, log],
     });
@@ -100,32 +105,97 @@ Environment (or ${ENV_FILES.at(-1)}):
     process.exit(1);
   };
 
-  const stopRouter = () => {
-    if (!existsSync(pidFile)) return console.log(`${spec.name}: no background router recorded.`);
-    const pid = Number(readFileSync(pidFile, "utf8"));
-    try {
-      process.kill(pid);
-      console.log(`${spec.name}: stopped router (pid ${pid}).`);
-    } catch {
-      console.log(`${spec.name}: router was not running.`);
+  // Pid files written before the project was renamed; a router started back then is still running.
+  const legacyPidFile = join(homedir(), ".jev-router", `${spec.client}.pid`);
+
+  const stopRouter = async () => {
+    // Whoever answers on the port is the router to stop; pid files only cover ones that don't say.
+    const candidates = [(await health())?.pid];
+    for (const file of [pidFile, legacyPidFile]) {
+      if (existsSync(file)) candidates.push(Number(readFileSync(file, "utf8")));
+      rmSync(file, { force: true });
+    }
+    const pids = [...new Set(candidates.filter((pid) => Number.isInteger(pid) && pid > 0))];
+    let stopped = false;
+    for (const pid of pids) {
+      try {
+        process.kill(pid);
+        stopped = true;
+        console.log(`${spec.name}: stopped router (pid ${pid}).`);
+      } catch {
+        // Already gone.
+      }
+    }
+    if (!stopped) console.log(`${spec.name}: no router was running.`);
+  };
+
+  /** Whichever opener this platform has; under WSL the browser lives on the Windows side. */
+  const openBrowser = async (url) => {
+    const wsl = process.platform === "linux" && Boolean(process.env.WSL_DISTRO_NAME);
+    const openers = [
+      ...(process.env.BROWSER ? [[process.env.BROWSER, url]] : []),
+      ...(process.platform === "darwin" ? [["open", url]] : []),
+      ...(process.platform === "win32" ? [["cmd", "/c", "start", "", url]] : []),
+      ...(wsl ? [["wslview", url], ["cmd.exe", "/c", "start", "", url]] : []),
+      ["xdg-open", url],
+    ];
+    for (const [command, ...args] of openers) {
+      const started = await new Promise((done) => {
+        const child = spawn(command, args, { stdio: "ignore", detached: true });
+        child.once("error", () => done(false));
+        child.once("spawn", () => (child.unref(), done(true)));
+      });
+      if (started) return;
     }
-    rmSync(pidFile, { force: true });
   };
 
-  const [flag] = process.argv.slice(2);
-  if (flag === "--jev-help") return console.log(help);
-  if (flag === "--jev-stop") return stopRouter();
-  if (flag === "--jev-config") return console.log(spec.configHelp(origin));
-  if (flag === "--jev-start") {
+  // Only names neither client uses: `--help` and `--config` stay theirs, so those two are spelled
+  // differently here. The original `--jev-*` spellings still work.
+  const LEGACY = { "--jev-config": "--print-config", "--jev-help": "--gateway-help" };
+  const [first] = process.argv.slice(2);
+  const flag = LEGACY[first] ?? first?.replace(/^--jev-(?=dashboard$|routing$|status$|logs$|start$|stop$)/, "--");
+  if (flag === "--gateway-help") return console.log(help);
+  if (flag === "--stop") return await stopRouter();
+  if (flag === "--routing") {
+    const wanted = process.argv[3];
+    if (wanted !== "on" && wanted !== "off") return console.error(`usage: ${spec.name} --routing on|off`);
+    await ensureRouter();
+    const key = process.env.ROUTER_API_KEY ? `&key=${encodeURIComponent(process.env.ROUTER_API_KEY)}` : "";
+    const response = await fetch(`${origin}/dashboard/routing?enabled=${wanted === "on"}${key}`, { method: "POST" });
+    if (!response.ok) return console.error(`${spec.name}: the router refused (${response.status}). Run \`${spec.name} --stop\` and try again.`);
+    return console.log(
+      wanted === "on"
+        ? `${spec.name}: routing on. Jev decides again.`
+        : `${spec.name}: routing off (baseline mode). Requests go straight to the LLM, tokens are still metered.`,
+    );
+  }
+  if (flag === "--print-config") return console.log(spec.configHelp(origin));
+  if (flag === "--start") {
     await ensureRouter();
     return console.log(`${spec.name}: router up on ${origin} → ${spec.upstream()} (logs: ${logFile})`);
   }
-  if (flag === "--jev-status") {
+  if (flag === "--status") {
     const running = await health();
     console.log(running ? `${spec.name}: router up on ${origin} → ${running.upstream}` : `${spec.name}: router is not running`);
     return console.log(`logs: ${logFile}`);
   }
-  if (flag === "--jev-logs") {
+  if (flag === "--dashboard") {
+    await ensureRouter();
+    // `localhost`, not 127.0.0.1: it is the name WSL forwards to a browser running on Windows.
+    const base = `http://localhost:${port}/dashboard`;
+    // The page looks for the other launchers' routers on their default ports; tell it about moved ones.
+    const peers = Object.entries(process.env).flatMap(([name, value]) => (/^JEV_[A-Z]+_PORT$/.test(name) && value !== String(port) ? [value] : []));
+    const url = peers.length ? `${base}?peers=${peers.join(",")}` : base;
+    const served = await fetch(url).then((response) => response.ok, () => false);
+    if (!served) {
+      console.error(`${spec.name}: the router on :${port} predates the dashboard. Run \`${spec.name} --stop\` and try again.`);
+      process.exit(1);
+    }
+    console.log(`${spec.name}: dashboard at ${url}`);
+    if (process.env.BROWSER !== "none") await openBrowser(url);
+    return;
+  }
+  if (flag === "--logs") {
     mkdirSync(STATE_DIR, { recursive: true });
     closeSync(openSync(logFile, "a"));
     return spawn("tail", ["-n", "30", "-f", logFile], { stdio: "inherit" });
@@ -140,7 +210,7 @@ Environment (or ${ENV_FILES.at(-1)}):
     console.error(`${spec.name}: could not run ${spec.client}: ${error.message}`);
     process.exit(127);
   });
-  // The router is left running for the next session; `--jev-stop` ends it.
+  // The router is left running for the next session; `--stop` ends it.
   child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
   // Ctrl-C reaches the client directly (same foreground process group); it decides what that means.
   process.on("SIGINT", () => {});

package/dist/app.js

@@ -4,9 +4,12 @@ import { Hono } from "hono";
 import { chatAdapter } from "./adapters/chat.js";
 import { messagesAdapter } from "./adapters/messages.js";
 import { responsesAdapter } from "./adapters/responses.js";
+import { dashboardRoutes } from "./dashboard.js";
 import { redactHeaders, summarizeResponse } from "./debug.js";
 import { decide } from "./decide.js";
+import { createEventLog } from "./events.js";
 import { forward } from "./upstream.js";
+import { readUsage } from "./usage.js";
 const safeEqual = (a, b) => {
     const left = Buffer.from(a);
     const right = Buffer.from(b);
@@ -44,8 +47,24 @@ function decisionHeaders(decision) {
     }
     return headers;
 }
-export function createApp({ config, askJev, fetch: fetchImpl = fetch, log = () => { }, dump }) {
+export function createApp({ config, askJev, fetch: fetchImpl = fetch, log: writeLog = () => { }, events = createEventLog(), dump }) {
     const app = new Hono();
+    /** One routed request: a line in the log, and a row on the dashboard. */
+    const log = (entry) => {
+        writeLog(entry);
+        events.record(entry);
+    };
+    /**
+     * Log a forwarded request once its reply has ended, because that is when the provider says what
+     * it cost. The reply is read from a clone in the background, so the client is never delayed.
+     */
+    const logWhenDone = (entry, response, startedAt) => {
+        const copy = response.clone();
+        void readUsage(copy).then((usage) => log({ ...entry, status: response.status, durationMs: Math.round(performance.now() - startedAt), ...(usage ? { usage } : {}) }));
+    };
+    // Routing can be switched off at runtime to measure a baseline: same clients, same traffic,
+    // same token accounting, but Jev is never asked and nothing is rewritten.
+    let routing = config.routing;
     /**
      * Error bodies are the only documentation an undocumented backend offers, and a finished
      * stream's usage is the only way to see what a rewrite did to the prompt cache: keep both.
@@ -80,6 +99,8 @@ export function createApp({ config, askJev, fetch: fetchImpl = fetch, log = () =
         return { decision: await decide(input, config, askJev), tools: input.tools.length };
     };
     const route = (adapter) => async (c) => {
+        const startedAt = performance.now();
+        const time = new Date().toISOString();
         const bytes = new Uint8Array(await c.req.arrayBuffer());
         // Unreadable bodies are not ours to judge: upstream produces its own error for them.
         const req = parseBody(bytes, c.req.header("content-encoding"));
@@ -95,9 +116,11 @@ export function createApp({ config, askJev, fetch: fetchImpl = fetch, log = () =
             decision = { mode: "passthrough", reason: "unparseable_body" };
         else if (c.req.header("x-jev-gateway") === "off")
             decision = { mode: "passthrough", reason: "disabled_by_header" };
+        else if (!routing)
+            decision = { mode: "passthrough", reason: "routing_disabled" };
         else
             ({ decision, tools } = await decideFor(adapter, req));
-        const entry = { event: "route", path: c.req.path, model: req?.model, tools: tools ?? req?.tools?.length ?? 0 };
+        const entry = { event: "route", time, path: c.req.path, model: req?.model, tools: tools ?? req?.tools?.length ?? 0 };
         if (req && decision.mode === "direct") {
             log({ ...entry, ...decision });
             const call = { tool: decision.tool, args: decision.args, inputTokens: decision.jev?.inputTokens ?? 0 };
@@ -117,7 +140,7 @@ export function createApp({ config, askJev, fetch: fetchImpl = fetch, log = () =
             const sent = { mode: decision.mode, model: rewritten.model, tool_choice: rewritten.tool_choice };
             dumpResponse("rejected", response, { sent });
             if (response.status !== 400 && response.status !== 422) {
-                log({ ...entry, ...decision, status: response.status });
+                logWhenDone({ ...entry, ...decision }, response, startedAt);
                 return response;
             }
             // The upstream refused the rewritten request (some backends only accept tool_choice
@@ -129,15 +152,18 @@ export function createApp({ config, askJev, fetch: fetchImpl = fetch, log = () =
             body: bytes,
             responseHeaders: decisionHeaders(decision),
         });
-        log({ ...entry, ...decision, status: response.status });
+        logWhenDone({ ...entry, ...decision }, response, startedAt);
         dumpResponse("upstream-error", response);
         return response;
     };
-    app.get("/health", (c) => c.json({ status: "ok", upstream: config.upstreamBaseUrl }));
+    app.get("/health", (c) => c.json({ status: "ok", pid: process.pid, upstream: config.upstreamBaseUrl }));
     app.use("*", async (c, next) => {
         if (!config.routerApiKey)
             return next();
-        const presented = c.req.header("authorization")?.replace(/^Bearer\s+/i, "") ?? "";
+        // A browser can't attach a header to a page it navigates to, so the dashboard — and only the
+        // dashboard — may carry the key as `?key=`.
+        const inQuery = c.req.path.startsWith("/dashboard") ? c.req.query("key") : undefined;
+        const presented = c.req.header("authorization")?.replace(/^Bearer\s+/i, "") ?? inQuery ?? "";
         if (safeEqual(presented, config.routerApiKey))
             return next();
         return c.json({ error: { message: "Invalid jev-gateway API key", type: "invalid_api_key" } }, 401);
@@ -163,6 +189,7 @@ export function createApp({ config, askJev, fetch: fetchImpl = fetch, log = () =
         const adapter = (adapters[format] ?? adapters[guess]);
         return c.json((await decideFor(adapter, req)).decision);
     });
+    app.route("/dashboard", dashboardRoutes(config, events, { get: () => routing, set: (enabled) => void (routing = enabled) }));
     app.post("/v1/chat/completions", route(chatAdapter));
     app.post("/v1/responses", route(responsesAdapter));
     app.post("/v1/messages", route(messagesAdapter));

package/dist/config.js

@@ -15,7 +15,7 @@ const bool = (env, key, fallback) => {
     const raw = str(env, key)?.toLowerCase();
     if (raw === undefined)
         return fallback;
-    return raw === "1" || raw === "true" || raw === "yes";
+    return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
 };
 export function loadConfig(env = process.env) {
     const onNone = str(env, "JEV_ON_NONE") ?? "force_none";
@@ -23,6 +23,7 @@ export function loadConfig(env = process.env) {
         throw new Error(`JEV_ON_NONE must be "force_none" or "passthrough", got "${onNone}"`);
     }
     const config = {
+        host: str(env, "HOST") ?? "127.0.0.1",
         port: num(env, "PORT", 8787),
         upstreamBaseUrl: (str(env, "UPSTREAM_BASE_URL") ?? "https://api.openai.com/v1").replace(/\/+$/, ""),
         upstreamApiKey: str(env, "UPSTREAM_API_KEY"),
@@ -34,9 +35,12 @@ export function loadConfig(env = process.env) {
         argMinCertainty: num(env, "JEV_ARG_MIN_CERTAINTY", 0.8),
         onNone,
         directCalls: bool(env, "JEV_DIRECT_CALLS", true),
+        routing: bool(env, "JEV_ROUTING", true),
         maxStateChars: num(env, "JEV_MAX_STATE_CHARS", 60_000),
         maxMessageChars: num(env, "JEV_MAX_MESSAGE_CHARS", 4_000),
         debugDumpDir: str(env, "JEV_DEBUG_DUMP_DIR"),
+        client: str(env, "JEV_CLIENT") ?? "standalone",
+        logFile: str(env, "JEV_LOG_FILE"),
     };
     if (config.routerApiKey && !config.upstreamApiKey) {
         throw new Error("ROUTER_API_KEY requires UPSTREAM_API_KEY (the client key is not valid upstream)");