mslxdff 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# mslxdfree
+
+Standalone **OpenCode Free** proxy — an OpenAI-compatible `/v1` gateway that forwards requests to the free zen gateway at `opencode.ai` (no account required) and exposes only the free models.
+
+Zero runtime dependencies: Node ≥ 20, built-in `node:http`, `node:crypto`, `node:test`.
+
+## What it does
+
+- `POST /v1/chat/completions` — forwards your OpenAI-format request to the upstream (with reasoning-content injection for thinking-mode DeepSeek/Kimi models), streams SSE back chunk-by-chunk, or passes through JSON for non-streaming calls.
+- `GET /v1/models` — the ~7 free models (`*-free` plus `big-pickle`), filtered from the full upstream list, cached for 10 minutes.
+- `GET /health` — public liveness check.
+
+## Install & run
+
+```
+npm install      # no deps actually fetched; just links the bin
+mslxdfree        # or: node bin/mslxdfree.js
+```
+
+First run generates a bearer token, writes it to the state file, and prints it:
+
+```
+mslxdfree listening on http://localhost:8080
+auth token: 9b5de021e914...
+endpoint:   http://localhost:8080/v1
+```
+
+### Daemon (background, stays resident)
+
+```
+mslxdfree -d        # start detached background daemon
+mslxdfree -stop     # stop it
+```
+
+Logs go to `~/.config/mslxdfree/daemon.log`, the daemon pid to `daemon.pid` (both overridable via `MSLXDFREE_DAEMON_DIR`). The daemon keeps running after your shell exits.
+
+### Token
+
+```
+mslxdfree -showtoken      # print the current token (creates one on first use)
+mslxdfree -refresh-token  # rotate it (prints the new token, does not start the server)
+```
+
+## Client configuration
+
+Point any OpenAI-compatible client at the endpoint with the token:
+
+```
+Endpoint:   http://localhost:8080/v1
+API Key:    <the bearer token>      (sent as Authorization: Bearer <token>)
+Model:      oc/deepseek-v4-flash-free   (the oc/ prefix is optional)
+```
+
+<x-model list>
+
+```
+$ curl -H "Authorization: Bearer <token>" http://localhost:8080/v1/models
+{"object":"list","data":[{"id":"big-pickle",...},{"id":"deepseek-v4-flash-free",...}, ...]}
+</x-model list>
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `PORT` | `8080` | listen port |
+| `MSLXDFREE_STATE_FILE` | `~/.config/mslxdfree/state.json` | token state file (mode 0600) |
+| `MSLXDFREE_DAEMON_DIR` | `~/.config/mslxdfree` | daemon pid + log directory |
+| `UPSTREAM_BASE_URL` | `https://opencode.ai` | upstream base |
+| `UPSTREAM_AUTH_TOKEN` | `public` | upstream `Authorization: Bearer <…>` value |
+| `UPSTREAM_CONNECT_TIMEOUT_MS` | `30000` | upstream connect timeout |
+| `LOG_LEVEL` | `info` | (reserved) |
+
+## Clients
+
+Point your OpenAI client at `http://<host>:8080/v1` (or the equivalent config seen above). Works for streaming and non-streaming chat completions.
+
+## Development
+
+```
+npm test        # node --test, no network access
+```
+
+The reference implementation is 9Router v0.5.45 (`/root/9router`); see `CLAUDE.md`, `CONTEXT.md`, and `docs/adr/` for the contract and the decisions behind it.

package/bin/mslxdfree.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { startServer } from "../src/server.js";
+import { createRouter } from "../src/routes.js";
+import { createUpstreamClient } from "../src/upstream.js";
+import { createModelsService } from "../src/models.js";
+import { loadToken, refreshToken } from "../src/state.js";
+import { startDaemon, stopDaemon, writePid, pidFile, logFile } from "../src/daemon.js";
+
+const args = process.argv.slice(2);
+
+if (args.includes("-refresh-token") || args.includes("--refresh-token")) {
+  const token = await refreshToken();
+  console.log(token);
+  process.exit(0);
+}
+
+if (args.includes("-showtoken") || args.includes("--showtoken")) {
+  const { token } = await loadToken();
+  console.log(token);
+  process.exit(0);
+}
+
+if (args.includes("-stop") || args.includes("--stop")) {
+  const { stopped, pid, reason } = stopDaemon();
+  if (stopped) {
+    console.log(`mslxdfree daemon stopped (pid ${pid})`);
+  } else {
+    console.log(`mslxdfree daemon not running${reason ? ` (${reason})` : ""}`);
+  }
+  process.exit(0);
+}
+
+if (args.includes("-d") || args.includes("--daemon")) {
+  if (!process.env.MSLXDFREE_DAEMON) {
+    // foreground: spawn the detached background instance, then wait for health
+    const spawnedPid = startDaemon(args.filter((a) => a !== "-d" && a !== "--daemon"));
+    await waitForHealth(4000);
+    console.log(`mslxdfree daemon started (pid ${spawnedPid})`);
+    console.log(`log: ${logFile()}`);
+    console.log(`pid: ${pidFile()}`);
+    process.exit(0);
+  }
+  // we ARE the daemon; stdout/stderr already point at the log file via startDaemon stdio
+}
+
+const { token, created } = await loadToken();
+const upstream = createUpstreamClient({});
+const baseUrl = process.env.UPSTREAM_BASE_URL || "https://opencode.ai";
+const models = createModelsService({ baseUrl, headers: upstream.headers });
+
+const router = createRouter({ token, upstream, models });
+const srv = startServer({ router });
+
+await srv.ready();
+if (process.env.MSLXDFREE_DAEMON) {
+  writePid(process.pid);
+}
+const addr = srv.server.address();
+const host = addr.address === "0.0.0.0" || addr.address === "::" ? "localhost" : addr.address;
+console.log(`mslxdfree listening on http://${host}:${addr.port}`);
+if (created) {
+  console.log(`auth token: ${token}`);
+}
+console.log(`endpoint:   http://${host}:${addr.port}/v1`);
+
+async function waitForHealth(timeoutMs) {
+  const start = Date.now();
+  const port = Number(process.env.PORT) || 8080;
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/health`);
+      if (res.ok) return;
+    } catch {
+      // not up yet
+    }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "mslxdff",
+  "version": "0.1.0",
+  "description": "Standalone OpenCode Free proxy — OpenAI-compatible /v1 gateway to opencode.ai zen (free models)",
+  "type": "module",
+  "bin": {
+    "mslxdfree": "bin/mslxdfree.js"
+  },
+  "scripts": {
+    "start": "node bin/mslxdfree.js",
+    "test": "node --test test/"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "keywords": [
+    "opencode",
+    "openai",
+    "proxy",
+    "free",
+    "zen"
+  ],
+  "license": "MIT"
+}

package/src/daemon.js

@@ -0,0 +1,63 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { join, dirname } from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+export function daemonDir() {
+  return process.env.MSLXDFREE_DAEMON_DIR || join(os.homedir(), ".config", "mslxdfree");
+}
+
+export function pidFile() {
+  return join(daemonDir(), "daemon.pid");
+}
+
+export function logFile() {
+  return join(daemonDir(), "daemon.log");
+}
+
+export function startDaemon(args = []) {
+  const here = fileURLToPath(import.meta.url);
+  const entry = here.endsWith("bin/mslxdfree.js")
+    ? here
+    : join(dirname(here), "..", "bin", "mslxdfree.js");
+  const dir = daemonDir();
+  mkdirSync(dir, { recursive: true });
+  const logFd = openSync(logFile(), "a", 0o600);
+  const child = spawn(process.execPath, [entry, ...args, "--daemon"], {
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+    env: { ...process.env, MSLXDFREE_DAEMON: "1" },
+  });
+  child.unref();
+  return child.pid;
+}
+
+export function writePid(pid) {
+  const dir = daemonDir();
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(pidFile(), String(pid), { mode: 0o600 });
+}
+
+export function readPid() {
+  if (!existsSync(pidFile())) return null;
+  const raw = readFileSync(pidFile(), "utf8").trim();
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 ? n : null;
+}
+
+export function stopDaemon() {
+  const pid = readPid();
+  if (!pid) return { stopped: false, reason: "no pid file" };
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch (err) {
+    if (err.code !== "ESRCH") throw err;
+  }
+  try {
+    unlinkSync(pidFile());
+  } catch {
+    // already gone
+  }
+  return { stopped: true, pid };
+}

package/src/models.js

@@ -0,0 +1,92 @@
+const KNOWN_FREE_OPENCODE_MODELS = ["big-pickle"];
+const CACHE_TTL_MS = 10 * 60 * 1000;
+
+export function isFreeModel(id) {
+  return (typeof id === "string" && id.endsWith("-free")) ||
+    KNOWN_FREE_OPENCODE_MODELS.includes(id);
+}
+
+export function filterFreeModels(list) {
+  const seen = new Set();
+  const out = [];
+  for (const m of list || []) {
+    if (!(m && m.id)) continue;
+    if (!isFreeModel(m.id)) continue;
+    if (seen.has(m.id)) continue;
+    seen.add(m.id);
+    out.push(m);
+  }
+  return out;
+}
+
+export function createModelsService({ baseUrl, headers, ttlMs = CACHE_TTL_MS } = {}) {
+  let cache = null;
+  let fetchedAt = 0;
+  let inflight = null;
+
+  async function get() {
+    const now = Date.now();
+    if (cache && now - fetchedAt < ttlMs) return cache;
+    if (inflight) return inflight;
+
+    inflight = (async () => {
+      try {
+        const data = await fetchUpstreamModels({ baseUrl, headers });
+        cache = data;
+        fetchedAt = Date.now();
+        return data;
+      } catch (err) {
+        // serve stale on failure if we have it, else rethrow
+        if (cache) return cache;
+        throw err;
+      } finally {
+        inflight = null;
+      }
+    })();
+    return inflight;
+  }
+
+  return { get };
+}
+
+async function fetchUpstreamModels({ baseUrl, headers, connectTimeoutMs = 30_000 }) {
+  const url = `${baseUrl}/zen/v1/models`;
+  for (let attempt = 0; ; attempt++) {
+    const res = await attemptFetch(url, headers, connectTimeoutMs);
+    if (res instanceof Error) {
+      if (attempt < NETWORK_RETRIES) continue;
+      throw res;
+    }
+    if (isRetryable(res.status) && attempt < STATUS_RETRIES) {
+      await sleep(2000);
+      continue;
+    }
+    if (!res.ok) throw new Error(`models fetch failed: HTTP ${res.status}`);
+    const json = await res.json().catch(() => ({}));
+    const raw = Array.isArray(json) ? json : json.data ?? json.models ?? [];
+    return { object: "list", data: filterFreeModels(raw) };
+  }
+}
+
+async function attemptFetch(url, headers, connectTimeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), connectTimeoutMs);
+  try {
+    return await fetch(url, { headers, signal: controller.signal });
+  } catch (err) {
+    return err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function isRetryable(status) {
+  return status === 429 || status === 502 || status === 503 || status === 504;
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+const NETWORK_RETRIES = 2;
+const STATUS_RETRIES = 2;

package/src/reasoning.js

@@ -0,0 +1,33 @@
+const PLACEHOLDER = " ";
+
+const MODEL_RULES = [
+  { match: (m) => /^kimi-/i.test(m || ""), scope: "toolCalls" },
+  { match: (m) => /deepseek/i.test(m || ""), scope: "all" },
+];
+
+export function normalizeModel(model) {
+  return model.startsWith("oc/") ? model.slice(3) : model;
+}
+
+function shouldInject(message, scope) {
+  if (message?.role !== "assistant") return false;
+  const rc = message.reasoning_content;
+  if (typeof rc === "string" && rc.length > 0) return false;
+  if (scope === "toolCalls") {
+    return Array.isArray(message.tool_calls) && message.tool_calls.length > 0;
+  }
+  return true;
+}
+
+function applyRule(body, rule) {
+  if (!rule || !body?.messages) return body;
+  const messages = body.messages.map((m) =>
+    shouldInject(m, rule.scope) ? { ...m, reasoning_content: PLACEHOLDER } : m
+  );
+  return { ...body, messages };
+}
+
+export function injectReasoningContent(model, body) {
+  const rule = MODEL_RULES.find((r) => r.match(model));
+  return applyRule(body, rule);
+}

package/src/routes.js

@@ -0,0 +1,125 @@
+import { timingSafeEqual, createHash } from "node:crypto";
+import { injectReasoningContent, normalizeModel } from "./reasoning.js";
+
+export const errMsg = (err) => String(err?.message || err);
+
+export function createRouter({ token, upstream, models }) {
+  return async function router(req, res) {
+    const method = req.method || "GET";
+    const path = (req.url || "").split("?")[0];
+
+    const route = ROUTES.find((r) => r.method === method && r.path === path);
+    if (!route) return notFound(res);
+
+    if (route.requiresAuth && !authorized(req, token)) {
+      res.statusCode = 401;
+      res.setHeader("WWW-Authenticate", "Bearer");
+      return json(res, 401, { error: "Unauthorized" });
+    }
+
+    await route.handler({ req, res, upstream, models });
+  };
+}
+
+function authorized(req, token) {
+  const header = req.headers["authorization"] || "";
+  const match = /^Bearer (.+)$/.exec(header);
+  if (!match) return false;
+  const digests = (s) => createHash("sha256").update(s).digest();
+  return timingSafeEqual(digests(match[1]), digests(token));
+}
+
+function json(res, status, body) {
+  res.statusCode = status;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify(body));
+}
+
+function notFound(res) {
+  return json(res, 404, { error: "Not Found" });
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    req.on("data", (c) => (data += c));
+    req.on("end", () => {
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch (err) {
+        reject(err);
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+const ROUTES = [
+  {
+    method: "GET",
+    path: "/health",
+    handler: ({ res }) => json(res, 200, { status: "ok" }),
+  },
+  {
+    method: "POST",
+    path: "/v1/chat/completions",
+    requiresAuth: true,
+    handler: async ({ req, res, upstream }) => {
+      let body;
+      try {
+        body = await readBody(req);
+      } catch {
+        return json(res, 400, { error: "Invalid JSON body" });
+      }
+
+      const model = normalizeModel(body.model || "");
+      const forwarded = { ...injectReasoningContent(model, body), model };
+      let upRes;
+      try {
+        upRes = await upstream.chat(forwarded);
+      } catch (err) {
+        return json(res, 502, { error: errMsg(err) });
+      }
+
+      const contentType = upRes.headers.get("content-type") || "";
+      const isStream = Boolean(body.stream) || contentType.includes("text/event-stream");
+      res.statusCode = upRes.status;
+
+      if (isStream) {
+        res.setHeader("Content-Type", "text/event-stream");
+        res.setHeader("Cache-Control", "no-cache");
+        res.setHeader("Connection", "keep-alive");
+        if (upRes.body) {
+          for await (const chunk of upRes.body) {
+            res.write(chunk);
+          }
+        }
+        res.end();
+        return;
+      }
+
+      const text = await upRes.text();
+      try {
+        json(res, upRes.status, JSON.parse(text));
+      } catch {
+        res.statusCode = upRes.status;
+        res.setHeader("Content-Type", contentType || "text/plain");
+        res.end(text);
+      }
+    },
+  },
+  {
+    method: "GET",
+    path: "/v1/models",
+    requiresAuth: true,
+    handler: async ({ res, models }) => {
+      if (!models) return json(res, 501, { error: "Models service not configured" });
+      try {
+        const data = await models.get();
+        json(res, 200, data);
+      } catch (err) {
+        json(res, 502, { error: errMsg(err) });
+      }
+    },
+  },
+];

package/src/server.js

@@ -0,0 +1,27 @@
+import { createServer as httpCreateServer } from "node:http";
+
+export function startServer({ router }, port = Number(process.env.PORT) || 8080) {
+  const server = httpCreateServer((req, res) => {
+    router(req, res).catch((err) => {
+      res.statusCode = 500;
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify({ error: String(err?.message || err) }));
+    });
+  });
+
+  const ready = () =>
+    new Promise((resolve, reject) => {
+      server.on("error", reject);
+      server.listen(port, resolve);
+    });
+
+  const close = () =>
+    new Promise((resolve) => {
+      server.close(resolve);
+    });
+
+  process.on("SIGINT", close);
+  process.on("SIGTERM", close);
+
+  return { server, ready, close };
+}

package/src/state.js

@@ -0,0 +1,39 @@
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import os from "node:os";
+
+export function defaultStateFile() {
+  return process.env.MSLXDFREE_STATE_FILE ||
+    join(os.homedir(), ".config", "mslxdfree", "state.json");
+}
+
+export function generateToken() {
+  return randomBytes(32).toString("hex");
+}
+
+export async function loadToken({ file = defaultStateFile() } = {}) {
+  try {
+    const saved = JSON.parse(readFileSync(file, "utf8"));
+    if (typeof saved.token === "string" && saved.token.length > 0) {
+      return { token: saved.token, created: false };
+    }
+  } catch {
+    // missing or unreadable → generate fresh below
+  }
+  return { token: writeToken(file), created: true };
+}
+
+export async function refreshToken({ file = defaultStateFile() } = {}) {
+  return writeToken(file);
+}
+
+function writeToken(file) {
+  const state = {
+    token: generateToken(),
+    createdAt: new Date().toISOString(),
+  };
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(state, null, 2), { mode: 0o600 });
+  return state.token;
+}

package/src/upstream.js

@@ -0,0 +1,68 @@
+export function createUpstreamClient({
+  baseUrl = process.env.UPSTREAM_BASE_URL || "https://opencode.ai",
+  authToken = process.env.UPSTREAM_AUTH_TOKEN || "public",
+  connectTimeoutMs = Number(process.env.UPSTREAM_CONNECT_TIMEOUT_MS) || 30_000,
+  retry = {
+    network: { attempts: 2, delayMs: 1000 },
+    429: { attempts: 2, delayMs: 2000 },
+    502: { attempts: 2, delayMs: 2000 },
+    503: { attempts: 2, delayMs: 2000 },
+    504: { attempts: 2, delayMs: 3000 },
+  },
+  fetchImpl = fetch,
+} = {}) {
+  const headers = {
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${authToken}`,
+    "x-opencode-client": "desktop",
+    "Accept": "text/event-stream",
+  };
+
+  async function chat(body) {
+    const url = `${baseUrl}/zen/v1/chat/completions`;
+    for (let attempt = 0; ; attempt++) {
+      const result = await attemptOnce(url, body);
+      if (result instanceof Error) {
+        const entry = retry?.network;
+        if (entry && attempt < entry.attempts) {
+          await sleep(entry.delayMs);
+          continue;
+        }
+        throw result;
+      }
+      const entry = retry?.[result.status];
+      if (entry && attempt < entry.attempts) {
+        await sleep(entry.delayMs);
+        continue;
+      }
+      return result;
+    }
+  }
+
+  async function attemptOnce(url, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() =>
+      controller.abort(new Error(`upstream timed out after ${connectTimeoutMs}ms`)),
+      connectTimeoutMs
+    );
+    try {
+      const res = await fetchImpl(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      return res;
+    } catch (err) {
+      return err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  return { chat, headers };
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}