@leoustc/service-llm 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @leoustc/service-llm
+
+Expose an OpenAI Codex subscription through OpenAI-compatible HTTP APIs and MCP.
+
+The service never executes model tool calls. It can return tool-call output to a client, which remains responsible for deciding whether to execute it.
+
+## Requirements
+
+- Node.js 22.19 or newer
+- A ChatGPT Plus or Pro account with Codex access
+
+## Install and log in
+
+```sh
+npm install --global @leoustc/service-llm
+service-llm login
+```
+
+For a headless machine, use the device-code flow:
+
+```sh
+service-llm login --device-code
+```
+
+OAuth credentials are stored at `~/.service-llm/auth.json` with owner-only permissions.
+
+If an API request arrives before login, the service starts a device-code login and returns HTTP 200 with `status: "ok"`, a friendly instruction, `device_code`, and `verification_uri`. Complete authentication in the browser, then retry the request.
+
+## Start the service
+
+```sh
+service-llm --port 7060 --api-key secret-one,secret-two
+```
+
+The default bind address is `127.0.0.1`. Use `--host 0.0.0.0` to listen on all interfaces. If no API keys are supplied, endpoints are unauthenticated.
+
+Clients can authenticate with either `Authorization: Bearer <key>` or `X-API-Key: <key>`.
+
+From a source checkout, build and run with request/response debug logging enabled:
+
+```sh
+make run
+make run PORT=8080 HOST=0.0.0.0 API_KEYS=secret-one,secret-two
+```
+
+Debug output includes request bodies, JSON responses, and individual SSE events. Authentication headers are redacted. Because prompts and model output are logged, do not enable debug logging around sensitive content.
+
+Install the current checkout to `~/.bin` without root permissions:
+
+```sh
+make install
+service-llm --help
+```
+
+If necessary, add it to your shell path with `export PATH="$HOME/.bin:$PATH"`. Run `make uninstall` to remove the symlink.
+
+## Endpoints
+
+- `GET /health`
+- `POST /v1/chat/completions`, including `stream: true` SSE responses
+- `POST /v1/responses`, including typed SSE responses
+- `POST /mcp`, providing the MCP `ask` tool. `ask` accepts a prompt plus optional `model`, `tools`, and `tool_choice`, and returns model tool calls without executing them.
+
+The default model is `gpt-5.4`. A different Codex model can be selected with the request's `model` field.
+
+## Development
+
+```sh
+make build
+make test
+make pack
+make publish
+make clean
+```
+
+Each test run also saves its complete output under `test/logs/` using a timestamped filename.
+The suite sends the live `Write a short story.` prompt through Chat Completions, Responses, and MCP `ask`. Override the HTTP request model with `make test TEST_MODEL=gpt-5.4-mini`.

package/dist/auth.js

@@ -0,0 +1,115 @@
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+  loginOpenAICodex,
+  loginOpenAICodexDeviceCode,
+  refreshOpenAICodexToken,
+} from "@earendil-works/pi-ai/oauth";
+
+export const authPath = join(homedir(), ".service-llm", "auth.json");
+let pendingDeviceLogin;
+
+async function saveAuth(data) {
+  await mkdir(dirname(authPath), { recursive: true, mode: 0o700 });
+  const temporaryPath = `${authPath}.${process.pid}.tmp`;
+  await writeFile(temporaryPath, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporaryPath, authPath);
+  await chmod(authPath, 0o600);
+}
+
+async function readAuth() {
+  try {
+    return JSON.parse(await readFile(authPath, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return {};
+    throw new Error(`Unable to read ${authPath}: ${error.message}`);
+  }
+}
+
+export async function login({ deviceCode = false } = {}) {
+  const credentials = deviceCode
+    ? await loginOpenAICodexDeviceCode({
+        onDeviceCode(info) {
+          console.error(`Open ${info.verificationUri} and enter code: ${info.userCode}`);
+        },
+      })
+    : await loginOpenAICodex({
+        onAuth(info) {
+          console.error(`Open this URL to log in:\n${info.url}`);
+        },
+        onPrompt: async () => {
+          throw new Error("OAuth callback timed out; retry with service-llm login --device-code");
+        },
+      });
+
+  const data = await readAuth();
+  data["openai-codex"] = { type: "oauth", ...credentials };
+  await saveAuth(data);
+  console.error(`Authentication saved to ${authPath}`);
+}
+
+export class DeviceLoginRequiredError extends Error {
+  constructor(info) {
+    super(`Authentication required. Please open ${info.verificationUri} and enter device code ${info.userCode}. After login completes, retry your request.`);
+    this.name = "DeviceLoginRequiredError";
+    this.deviceCode = info.userCode;
+    this.verificationUri = info.verificationUri;
+    this.expiresInSeconds = info.expiresInSeconds;
+  }
+}
+
+async function beginDeviceLogin() {
+  if (pendingDeviceLogin) return pendingDeviceLogin.info;
+
+  let resolveInfo;
+  let rejectInfo;
+  const infoPromise = new Promise((resolve, reject) => {
+    resolveInfo = resolve;
+    rejectInfo = reject;
+  });
+  pendingDeviceLogin = { info: infoPromise };
+
+  loginOpenAICodexDeviceCode({
+    onDeviceCode(info) {
+      const publicInfo = {
+        userCode: info.userCode,
+        verificationUri: info.verificationUri,
+        expiresInSeconds: info.expiresInSeconds,
+      };
+      pendingDeviceLogin.info = Promise.resolve(publicInfo);
+      resolveInfo(publicInfo);
+      console.error(`Authentication required: open ${info.verificationUri} and enter ${info.userCode}`);
+    },
+  })
+    .then(async (credentials) => {
+      const data = await readAuth();
+      data["openai-codex"] = { type: "oauth", ...credentials };
+      await saveAuth(data);
+      console.error(`Authentication completed and saved to ${authPath}`);
+    })
+    .catch((error) => {
+      rejectInfo(error);
+      console.error(`Device login failed: ${error.message ?? String(error)}`);
+    })
+    .finally(() => {
+      pendingDeviceLogin = undefined;
+    });
+
+  return infoPromise;
+}
+
+export async function getAccessToken() {
+  const data = await readAuth();
+  let credentials = data["openai-codex"];
+  if (!credentials?.access || !credentials?.refresh || !credentials?.expires) {
+    throw new DeviceLoginRequiredError(await beginDeviceLogin());
+  }
+
+  if (Date.now() >= credentials.expires - 60_000) {
+    credentials = { type: "oauth", ...(await refreshOpenAICodexToken(credentials.refresh)) };
+    data["openai-codex"] = credentials;
+    await saveAuth(data);
+  }
+  return credentials.access;
+}

package/dist/backend.js

@@ -0,0 +1,79 @@
+import { getModel, stream } from "@earendil-works/pi-ai/compat";
+import { getAccessToken } from "./auth.js";
+
+export const defaultModel = "gpt-5.4";
+
+function textFromContent(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((part) => part?.type === "text" || part?.type === "input_text")
+    .map((part) => part.text ?? "")
+    .join("\n");
+}
+
+export function messagesFromChat(messages = []) {
+  let systemPrompt;
+  const result = [];
+  for (const message of messages) {
+    const text = textFromContent(message.content);
+    if (message.role === "system" || message.role === "developer") {
+      systemPrompt = systemPrompt ? `${systemPrompt}\n\n${text}` : text;
+    } else if (message.role === "user") {
+      result.push({ role: "user", content: text, timestamp: Date.now() });
+    } else if (message.role === "assistant") {
+      result.push({
+        role: "assistant",
+        content: [{ type: "text", text }],
+        api: "openai-codex-responses",
+        provider: "openai-codex",
+        model: defaultModel,
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        stopReason: "stop",
+        timestamp: Date.now(),
+      });
+    }
+  }
+  return { systemPrompt, messages: result };
+}
+
+export function messagesFromResponses(input) {
+  if (typeof input === "string") {
+    return { messages: [{ role: "user", content: input, timestamp: Date.now() }] };
+  }
+  return messagesFromChat(Array.isArray(input) ? input : []);
+}
+
+function toolsFromOpenAI(tools) {
+  if (!Array.isArray(tools)) return undefined;
+  return tools.flatMap((tool) => {
+    const fn = tool.type === "function" ? (tool.function ?? tool) : null;
+    return fn?.name
+      ? [{ name: fn.name, description: fn.description ?? "", parameters: fn.parameters ?? { type: "object", properties: {} } }]
+      : [];
+  });
+}
+
+export async function createCompletionStream({ context, model = defaultModel, tools, toolChoice, signal }) {
+  const selectedModel = getModel("openai-codex", model) ?? getModel("openai-codex", defaultModel);
+  if (!selectedModel) throw new Error(`Unknown Codex model: ${model}`);
+  const apiKey = await getAccessToken();
+  return stream(selectedModel, { ...context, tools: toolsFromOpenAI(tools) }, {
+    apiKey,
+    signal,
+    onPayload(payload) {
+      if (!toolChoice || !payload || typeof payload !== "object") return payload;
+      return { ...payload, tool_choice: toolChoice };
+    },
+  });
+}
+
+export function contentFromMessage(message) {
+  return message.content.filter((part) => part.type === "text").map((part) => part.text).join("");
+}
+
+export function toolCallsFromMessage(message) {
+  return message.content
+    .filter((part) => part.type === "toolCall")
+    .map((part) => ({ id: part.id, type: "function", function: { name: part.name, arguments: JSON.stringify(part.arguments) } }));
+}

package/dist/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { login } from "./auth.js";
+import { startServer } from "./http.js";
+
+function usage() {
+  console.error(`Usage:
+  service-llm login [--device-code]
+  service-llm [--port 7060] [--host 127.0.0.1] [--api-key key1,key2]`);
+}
+
+function valueAfter(args, names, fallback) {
+  const index = args.findIndex((arg) => names.includes(arg));
+  return index < 0 ? fallback : args[index + 1];
+}
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  usage();
+} else if (args[0] === "login") {
+  await login({ deviceCode: args.includes("--device-code") });
+} else {
+  const port = Number(valueAfter(args, ["--port"], "7060"));
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("--port must be between 1 and 65535");
+  const apiKeyValue = valueAfter(args, ["--api-key", "-api_key"], process.env.SERVICE_LLM_API_KEYS ?? "");
+  startServer({ port, host: valueAfter(args, ["--host"], "127.0.0.1"), apiKeys: apiKeyValue.split(",").map((key) => key.trim()) });
+}

package/dist/http.js

@@ -0,0 +1,205 @@
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { DeviceLoginRequiredError } from "./auth.js";
+import {
+  contentFromMessage,
+  createCompletionStream,
+  defaultModel,
+  messagesFromChat,
+  messagesFromResponses,
+  toolCallsFromMessage,
+} from "./backend.js";
+
+const jsonHeaders = { "content-type": "application/json; charset=utf-8" };
+const debugEnabled = ["1", "true", "yes", "service-llm", "*"].includes((process.env.DEBUG ?? "").toLowerCase());
+
+function debug(direction, value) {
+  if (!debugEnabled) return;
+  const rendered = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+  console.error(`[service-llm] ${direction}\n${rendered}`);
+}
+
+function sendJson(response, status, body) {
+  debug(`response ${status}`, body);
+  response.writeHead(status, jsonHeaders);
+  response.end(JSON.stringify(body));
+}
+
+async function readJson(request) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > 10 * 1024 * 1024) throw Object.assign(new Error("Request body too large"), { status: 413 });
+    chunks.push(chunk);
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+  } catch {
+    throw Object.assign(new Error("Invalid JSON body"), { status: 400 });
+  }
+}
+
+function isAuthorized(request, apiKeys) {
+  if (apiKeys.size === 0) return true;
+  const authorization = request.headers.authorization ?? "";
+  const token = authorization.startsWith("Bearer ") ? authorization.slice(7) : request.headers["x-api-key"];
+  return typeof token === "string" && apiKeys.has(token);
+}
+
+function sse(response, event) {
+  debug("response SSE", event);
+  response.write(`data: ${JSON.stringify(event)}\n\n`);
+}
+
+async function collect(streamResult) {
+  let result;
+  for await (const event of streamResult) {
+    if (event.type === "done") result = event.message;
+    if (event.type === "error") throw new Error(event.error.errorMessage ?? "Model request failed");
+  }
+  if (!result) throw new Error("Model returned no result");
+  return result;
+}
+
+async function chatCompletions(request, response, body) {
+  const id = `chatcmpl-${randomUUID().replaceAll("-", "")}`;
+  const model = body.model || defaultModel;
+  const streamResult = await createCompletionStream({
+    context: messagesFromChat(body.messages), model, tools: body.tools, toolChoice: body.tool_choice,
+  });
+  if (body.stream) {
+    response.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" });
+    sse(response, { id, object: "chat.completion.chunk", created: Math.floor(Date.now() / 1000), model, choices: [{ index: 0, delta: { role: "assistant" }, finish_reason: null }] });
+    for await (const event of streamResult) {
+      if (event.type === "text_delta") sse(response, { id, object: "chat.completion.chunk", created: Math.floor(Date.now() / 1000), model, choices: [{ index: 0, delta: { content: event.delta }, finish_reason: null }] });
+      if (event.type === "toolcall_end") sse(response, { id, object: "chat.completion.chunk", created: Math.floor(Date.now() / 1000), model, choices: [{ index: 0, delta: { tool_calls: [{ index: event.contentIndex, id: event.toolCall.id, type: "function", function: { name: event.toolCall.name, arguments: JSON.stringify(event.toolCall.arguments) } }] }, finish_reason: null }] });
+      if (event.type === "done") sse(response, { id, object: "chat.completion.chunk", created: Math.floor(Date.now() / 1000), model, choices: [{ index: 0, delta: {}, finish_reason: event.reason === "toolUse" ? "tool_calls" : event.reason }] });
+      if (event.type === "error") throw new Error(event.error.errorMessage ?? "Model request failed");
+    }
+    debug("response SSE", "[DONE]");
+    response.end("data: [DONE]\n\n");
+    return;
+  }
+  const message = await collect(streamResult);
+  const toolCalls = toolCallsFromMessage(message);
+  sendJson(response, 200, { id, object: "chat.completion", created: Math.floor(Date.now() / 1000), model, choices: [{ index: 0, message: { role: "assistant", content: contentFromMessage(message), ...(toolCalls.length ? { tool_calls: toolCalls } : {}) }, finish_reason: message.stopReason === "toolUse" ? "tool_calls" : message.stopReason }], usage: { prompt_tokens: message.usage.input, completion_tokens: message.usage.output, total_tokens: message.usage.totalTokens } });
+}
+
+function responseObject(id, model, message, status = "completed") {
+  const output = [];
+  const text = contentFromMessage(message);
+  if (text) output.push({ id: `msg_${randomUUID().replaceAll("-", "")}`, type: "message", status: "completed", role: "assistant", content: [{ type: "output_text", text, annotations: [] }] });
+  for (const call of toolCallsFromMessage(message)) output.push({ type: "function_call", id: call.id, call_id: call.id, name: call.function.name, arguments: call.function.arguments, status: "completed" });
+  return { id, object: "response", created_at: Math.floor(Date.now() / 1000), status, model, output, usage: { input_tokens: message.usage.input, output_tokens: message.usage.output, total_tokens: message.usage.totalTokens } };
+}
+
+async function responses(request, response, body) {
+  const id = `resp_${randomUUID().replaceAll("-", "")}`;
+  const model = body.model || defaultModel;
+  const streamResult = await createCompletionStream({ context: messagesFromResponses(body.input), model, tools: body.tools, toolChoice: body.tool_choice });
+  if (body.stream) {
+    response.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" });
+    const created = { id, object: "response", created_at: Math.floor(Date.now() / 1000), status: "in_progress", model, output: [] };
+    sse(response, { type: "response.created", response: created });
+    let sequenceNumber = 0;
+    let outputIndex = 0;
+    for await (const event of streamResult) {
+      if (event.type === "text_delta") sse(response, { type: "response.output_text.delta", sequence_number: sequenceNumber++, output_index: 0, content_index: 0, delta: event.delta });
+      if (event.type === "toolcall_end") sse(response, { type: "response.output_item.done", sequence_number: sequenceNumber++, output_index: outputIndex++, item: { type: "function_call", id: event.toolCall.id, call_id: event.toolCall.id, name: event.toolCall.name, arguments: JSON.stringify(event.toolCall.arguments), status: "completed" } });
+      if (event.type === "done") sse(response, { type: "response.completed", sequence_number: sequenceNumber++, response: responseObject(id, model, event.message) });
+      if (event.type === "error") throw new Error(event.error.errorMessage ?? "Model request failed");
+    }
+    debug("response SSE", "<stream closed>");
+    response.end();
+    return;
+  }
+  sendJson(response, 200, responseObject(id, model, await collect(streamResult)));
+}
+
+async function ask({ prompt, model = defaultModel, tools, toolChoice }) {
+  const streamResult = await createCompletionStream({
+    context: messagesFromResponses(prompt),
+    model,
+    tools,
+    toolChoice,
+  });
+  const message = await collect(streamResult);
+  return { text: contentFromMessage(message), toolCalls: toolCallsFromMessage(message), model };
+}
+
+async function mcp(response, body) {
+  const base = { jsonrpc: "2.0", id: body.id };
+  if (body.method === "initialize") return sendJson(response, 200, { ...base, result: { protocolVersion: body.params?.protocolVersion ?? "2025-03-26", capabilities: { tools: {} }, serverInfo: { name: "service-llm", version: "0.1.0" } } });
+  if (body.method === "notifications/initialized") return response.writeHead(202).end();
+  if (body.method === "ping") return sendJson(response, 200, { ...base, result: {} });
+  if (body.method === "tools/list") return sendJson(response, 200, { ...base, result: { tools: [{ name: "ask", description: "Ask a Codex model a question and optionally allow it to return function tool calls. Tool calls are never executed.", inputSchema: { type: "object", properties: { prompt: { type: "string" }, model: { type: "string" }, tools: { type: "array", items: { type: "object" } }, tool_choice: {} }, required: ["prompt"], additionalProperties: false } }] } });
+  if (body.method === "tools/call" && body.params?.name === "ask") {
+    if (typeof body.params.arguments?.prompt !== "string") return sendJson(response, 200, { ...base, error: { code: -32602, message: "ask requires a string prompt" } });
+    const answer = await ask({
+      prompt: body.params.arguments.prompt,
+      model: body.params.arguments.model,
+      tools: body.params.arguments.tools,
+      toolChoice: body.params.arguments.tool_choice,
+    });
+    const structuredContent = {
+      model: answer.model,
+      text: answer.text,
+      tool_calls: answer.toolCalls,
+    };
+    return sendJson(response, 200, {
+      ...base,
+      result: {
+        content: [{ type: "text", text: answer.toolCalls.length ? JSON.stringify(structuredContent) : answer.text }],
+        structuredContent,
+      },
+    });
+  }
+  return sendJson(response, 200, { ...base, error: { code: -32601, message: "Method not found" } });
+}
+
+export function startServer({ port = 7060, host = "127.0.0.1", apiKeys = [] } = {}) {
+  const allowedKeys = new Set(apiKeys.filter(Boolean));
+  const server = createServer(async (request, response) => {
+    try {
+      const url = new URL(request.url, `http://${request.headers.host ?? "localhost"}`);
+      debug("request", {
+        method: request.method,
+        path: url.pathname,
+        headers: {
+          accept: request.headers.accept,
+          "content-type": request.headers["content-type"],
+          authorization: request.headers.authorization ? "<redacted>" : undefined,
+          "x-api-key": request.headers["x-api-key"] ? "<redacted>" : undefined,
+        },
+      });
+      if (request.method === "GET" && url.pathname === "/health") return sendJson(response, 200, { status: "ok" });
+      if (!isAuthorized(request, allowedKeys)) return sendJson(response, 401, { error: { message: "Invalid API key", type: "authentication_error" } });
+      if (request.method !== "POST") return sendJson(response, 405, { error: { message: "Method not allowed" } });
+      const body = await readJson(request);
+      debug("request body", body);
+      if (url.pathname === "/v1/chat/completions") return await chatCompletions(request, response, body);
+      if (url.pathname === "/v1/responses") return await responses(request, response, body);
+      if (url.pathname === "/mcp") return await mcp(response, body);
+      return sendJson(response, 404, { error: { message: "Not found" } });
+    } catch (error) {
+      if (response.headersSent) return response.destroy(error);
+      if (error instanceof DeviceLoginRequiredError) {
+        return sendJson(response, 200, {
+          status: "ok",
+          authentication_required: true,
+          message: error.message,
+          device_code: error.deviceCode,
+          verification_uri: error.verificationUri,
+          expires_in: error.expiresInSeconds,
+        });
+      }
+      sendJson(response, error.status ?? 500, { error: { message: error.message ?? String(error), type: "service_error" } });
+    }
+  });
+  server.listen(port, host, () => {
+    console.error(`service-llm listening on http://${host}:${port}`);
+    if (debugEnabled) console.error("[service-llm] DEBUG logging enabled");
+  });
+  return server;
+}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { authPath, getAccessToken, login } from "./auth.js";
+export { defaultModel } from "./backend.js";
+export { startServer } from "./http.js";

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@leoustc/service-llm",
+  "version": "0.1.0",
+  "description": "Expose a Codex subscription through OpenAI-compatible and MCP endpoints.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "service-llm": "./dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "node ./scripts/build.mjs",
+    "clean": "node ./scripts/clean.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "0.80.6"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}