@jiayunxie/aerial 0.1.0

package/src/probe.js

@@ -0,0 +1,141 @@
+import { proxyChatCompletions, proxyMessages, proxyModels, proxyResponses } from "./copilot.js";
+
+function modelRoutes(model) {
+  return model.aerial?.routes || [];
+}
+
+function firstModel(models, route) {
+  return models.find((model) => modelRoutes(model).includes(route));
+}
+
+async function readJson(response) {
+  const text = await response.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}
+
+function tokenSummary(payload) {
+  const usage = payload.usage || {};
+  return {
+    input: usage.input_tokens ?? usage.prompt_tokens,
+    output: usage.output_tokens ?? usage.completion_tokens,
+    cached: usage.input_tokens_details?.cached_tokens ?? usage.prompt_tokens_details?.cached_tokens ?? usage.cache_read_input_tokens
+  };
+}
+
+async function probeRoute(name, model, handler, payload, headers = {}) {
+  const response = await handler(new Request(`http://aerial.local/probe/${name}`, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...headers },
+    body: JSON.stringify(payload)
+  }));
+  const body = await readJson(response);
+  return {
+    route: name,
+    model: model.id,
+    ok: response.ok,
+    status: response.status,
+    contentType: response.headers.get("content-type") || undefined,
+    usage: response.ok ? tokenSummary(body) : undefined,
+    error: response.ok ? undefined : body.error || body
+  };
+}
+
+function summarizeModels(models) {
+  const summary = { responses: 0, messages: 0, chat: 0, websocketResponses: 0, embeddings: 0, unsupported: 0 };
+  for (const model of models) {
+    const routes = modelRoutes(model);
+    if (routes.includes("responses")) summary.responses += 1;
+    if (routes.includes("messages")) summary.messages += 1;
+    if (routes.includes("chat")) summary.chat += 1;
+    if (modelRoutes(model).includes("responses_websocket")) summary.websocketResponses += 1;
+    if (model.aerial?.notes?.includes("embeddings_not_implemented")) summary.embeddings += 1;
+    if (!model.aerial?.supported) summary.unsupported += 1;
+  }
+  return summary;
+}
+
+export async function runProbe({ live = false } = {}) {
+  const modelsResponse = await proxyModels(new Request("http://aerial.local/v1/models", { method: "GET" }));
+  const modelsPayload = await readJson(modelsResponse);
+  if (!modelsResponse.ok) {
+    return { ok: false, generatedAt: new Date().toISOString(), error: modelsPayload.error || modelsPayload };
+  }
+
+  const models = Array.isArray(modelsPayload.data) ? modelsPayload.data : [];
+  const report = {
+    ok: true,
+    generatedAt: new Date().toISOString(),
+    live,
+    summary: summarizeModels(models),
+    routes: [],
+    models: models.map((model) => ({
+      id: model.id,
+      routes: modelRoutes(model),
+      notes: model.aerial?.notes || [],
+      supported: Boolean(model.aerial?.supported)
+    }))
+  };
+
+  if (!live) return report;
+
+  const responsesModel = firstModel(models, "responses");
+  if (responsesModel) {
+    report.routes.push(await probeRoute("responses", responsesModel, proxyResponses, {
+      model: responsesModel.id,
+      input: "Return only: aerial-probe",
+      max_output_tokens: 16,
+      store: false
+    }));
+  }
+
+  const messagesModel = firstModel(models, "messages");
+  if (messagesModel) {
+    report.routes.push(await probeRoute("messages", messagesModel, proxyMessages, {
+      model: messagesModel.id,
+      max_tokens: 16,
+      messages: [{ role: "user", content: "Return only: aerial-probe" }]
+    }, { "anthropic-version": "2023-06-01" }));
+  }
+
+  const chatModel = firstModel(models, "chat");
+  if (chatModel) {
+    report.routes.push(await probeRoute("chat", chatModel, proxyChatCompletions, {
+      model: chatModel.id,
+      messages: [{ role: "user", content: "Return only: aerial-probe" }],
+      max_completion_tokens: 16
+    }));
+  }
+
+  return report;
+}
+
+export function formatProbeReport(report) {
+  if (!report.ok) return `Aerial probe failed: ${JSON.stringify(report.error)}`;
+  const lines = [
+    `Aerial probe (${report.live ? "live" : "models"}) at ${report.generatedAt}`,
+    `Models: ${report.models.length}`,
+    `Routes: responses=${report.summary.responses}, responsesWebSocket=${report.summary.websocketResponses}, messages=${report.summary.messages}, chat=${report.summary.chat}`,
+    `Unsupported: embeddings=${report.summary.embeddings}, noRoute=${report.summary.unsupported}`
+  ];
+
+  if (report.routes.length) {
+    lines.push("", "Live route checks:");
+    for (const route of report.routes) {
+      const usage = route.usage ? ` input=${route.usage.input ?? "?"} output=${route.usage.output ?? "?"} cached=${route.usage.cached ?? 0}` : "";
+      lines.push(`- ${route.route}: ${route.ok ? "ok" : "fail"} status=${route.status} model=${route.model}${usage}`);
+    }
+  }
+
+  lines.push("", "Model matrix:");
+  for (const model of report.models) {
+    const routes = model.routes.length ? model.routes.join(",") : "-";
+    const notes = model.notes.length ? ` notes=${model.notes.join(",")}` : "";
+    lines.push(`- ${model.id}: routes=${routes}${notes}`);
+  }
+  return lines.join("\n");
+}

package/src/responses-websocket.js

@@ -0,0 +1,111 @@
+import { WebSocket } from "undici";
+import { COPILOT_API_ORIGIN } from "./constants.js";
+
+const TERMINAL_RESPONSE_TYPES = new Set([
+  "response.completed",
+  "response.failed",
+  "response.incomplete",
+  "error"
+]);
+
+function websocketUrl() {
+  const url = new URL(`${COPILOT_API_ORIGIN}/responses`);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return url.toString();
+}
+
+function normalizeMessageData(data) {
+  if (typeof data === "string") return data;
+  if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);
+  if (ArrayBuffer.isView(data)) return new TextDecoder().decode(data);
+  if (data && typeof data.text === "function") return data.text();
+  return String(data);
+}
+
+function toSseFrame(message) {
+  if (message === "[DONE]") return "data: [DONE]\n\n";
+  try {
+    const parsed = JSON.parse(message);
+    const lines = [];
+    if (typeof parsed.id === "string") lines.push(`id: ${parsed.id}`);
+    if (typeof parsed.type === "string") lines.push(`event: ${parsed.type}`);
+    lines.push(`data: ${JSON.stringify(parsed)}`);
+    return `${lines.join("\n")}\n\n`;
+  } catch {
+    return `data: ${message}\n\n`;
+  }
+}
+
+function isTerminalMessage(message) {
+  if (!message || message === "[DONE]") return false;
+  try {
+    return TERMINAL_RESPONSE_TYPES.has(JSON.parse(message).type);
+  } catch {
+    return false;
+  }
+}
+
+function openWebSocket(headers) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(websocketUrl(), { headers });
+    const cleanup = () => {
+      ws.removeEventListener("open", onOpen);
+      ws.removeEventListener("error", onError);
+    };
+    const onOpen = () => {
+      cleanup();
+      resolve(ws);
+    };
+    const onError = (event) => {
+      cleanup();
+      reject(new Error(`Failed to create responses websocket: ${event?.message || event?.error?.message || "unknown error"}`));
+    };
+    ws.addEventListener("open", onOpen);
+    ws.addEventListener("error", onError);
+  });
+}
+
+export function supportsResponsesWebSocket(model) {
+  return Array.isArray(model?.supported_endpoints) && model.supported_endpoints.includes("ws:/responses");
+}
+
+export function isResponsesWebSocketOptIn() {
+  return process.env.AERIAL_RESPONSES_WEBSOCKET === "on";
+}
+
+export function shouldUseResponsesWebSocket(payload, model) {
+  if (!isResponsesWebSocketOptIn()) return false;
+  if (!payload?.stream) return false;
+  return supportsResponsesWebSocket(model);
+}
+
+export async function proxyResponsesWebSocket(payload, headers, { initiator = "user" } = {}) {
+  const ws = await openWebSocket(headers);
+  ws.send(JSON.stringify({ ...payload, type: "response.create", initiator }));
+
+  const encoder = new TextEncoder();
+  return new Response(new ReadableStream({
+    start(controller) {
+      const close = () => {
+        try { ws.close(); } catch {}
+      };
+      ws.addEventListener("message", async (event) => {
+        const message = await normalizeMessageData(event.data);
+        controller.enqueue(encoder.encode(toSseFrame(message)));
+        if (isTerminalMessage(message)) {
+          controller.close();
+          close();
+        }
+      });
+      ws.addEventListener("close", () => {
+        try { controller.close(); } catch {}
+      });
+      ws.addEventListener("error", (event) => {
+        controller.error(new Error(event?.message || event?.error?.message || "Responses websocket stream error"));
+      });
+    },
+    cancel() {
+      try { ws.close(); } catch {}
+    }
+  }), { headers: { "content-type": "text/event-stream" } });
+}

package/src/server.js

@@ -0,0 +1,101 @@
+import http from "node:http";
+import { DEFAULT_HOST, DEFAULT_PORT } from "./constants.js";
+import { loadConfig, validateLocalAuth } from "./config.js";
+import { proxyChatCompletions, proxyMessages, proxyModels, proxyResponses, localCountTokens } from "./copilot.js";
+import { logEvent } from "./log.js";
+
+function json(status, body) {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+}
+
+function nodeRequestToFetch(req, body, signal) {
+  return new Request(`http://${req.headers.host}${req.url}`, { method: req.method, headers: req.headers, body: body.length ? body : undefined, duplex: "half", signal });
+}
+
+async function readBody(req) {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  return Buffer.concat(chunks);
+}
+
+async function handle(fetchRequest, runtime = {}) {
+  const url = new URL(fetchRequest.url);
+  const config = loadConfig();
+  if (fetchRequest.method === "GET" && url.pathname === "/health") {
+    return Response.json({ ok: true, service: "aerial", host: runtime.host || config.host, port: runtime.port || config.port });
+  }
+
+  if (!validateLocalAuth(Object.fromEntries(fetchRequest.headers), config)) {
+    return json(401, { error: { type: "authentication_error", message: "Invalid or missing Aerial API key" } });
+  }
+
+  if (fetchRequest.method === "GET" && url.pathname === "/v1/models") return proxyModels(fetchRequest);
+  if (fetchRequest.method === "POST" && url.pathname === "/v1/responses") return proxyResponses(fetchRequest);
+  if (fetchRequest.method === "POST" && url.pathname === "/v1/messages") return proxyMessages(fetchRequest);
+  if (fetchRequest.method === "POST" && url.pathname === "/v1/messages/count_tokens") return localCountTokens(fetchRequest);
+  if (fetchRequest.method === "POST" && url.pathname === "/v1/chat/completions") return proxyChatCompletions(fetchRequest);
+  return json(404, { error: { type: "not_found", message: `No route for ${fetchRequest.method} ${url.pathname}` } });
+}
+
+async function writeNodeResponse(res, fetchResponse, signal) {
+  res.statusCode = fetchResponse.status;
+  fetchResponse.headers.forEach((value, key) => res.setHeader(key, value));
+  if (!fetchResponse.body) {
+    res.end();
+    return;
+  }
+  const reader = fetchResponse.body.getReader();
+  try {
+    while (!signal?.aborted) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!res.write(Buffer.from(value))) {
+        await new Promise((resolve) => res.once("drain", resolve));
+      }
+    }
+  } finally {
+    if (signal?.aborted) await reader.cancel().catch(() => {});
+  }
+  if (!res.destroyed) res.end();
+}
+
+export function createServer(runtime = {}) {
+  const server = http.createServer(async (req, res) => {
+    const started = Date.now();
+    const controller = new AbortController();
+    res.on("close", () => controller.abort());
+    try {
+      logEvent("request_start", { method: req.method, path: req.url });
+      const body = await readBody(req);
+      const fetchRequest = nodeRequestToFetch(req, body, controller.signal);
+      const fetchResponse = await handle(fetchRequest, runtime);
+      await writeNodeResponse(res, fetchResponse, controller.signal);
+      logEvent("request_end", { method: req.method, path: req.url, status: fetchResponse.status, ms: Date.now() - started });
+    } catch (error) {
+      if (error.name === "AbortError" || res.destroyed) {
+        logEvent("request_aborted", { method: req.method, path: req.url, ms: Date.now() - started });
+        return;
+      }
+      logEvent("request_end", { method: req.method, path: req.url, status: 500, ms: Date.now() - started, error: error.message });
+      res.statusCode = error.message?.includes("Missing GitHub token") ? 503 : 500;
+      res.setHeader("content-type", "application/json");
+      res.end(JSON.stringify({ error: { type: "aerial_error", message: error.message } }));
+    }
+  });
+
+  server.on("upgrade", (req, socket) => {
+    logEvent("websocket_unsupported", { path: req.url });
+    socket.end("HTTP/1.1 501 Not Implemented\r\ncontent-type: application/json\r\nconnection: close\r\n\r\n{\"error\":{\"type\":\"not_implemented\",\"message\":\"Aerial does not expose a client WebSocket. Use HTTP POST /v1/responses; the upstream ws:/responses path is an internal opt-in transport (AERIAL_RESPONSES_WEBSOCKET=on) and is never proxied to clients.\"}}");
+  });
+
+  return server;
+}
+
+export function startServer({ host, port } = {}) {
+  const config = loadConfig();
+  const bindHost = host || config.host || DEFAULT_HOST;
+  const bindPort = Number(port || config.port || DEFAULT_PORT);
+  const server = createServer({ host: bindHost, port: bindPort });
+  server.listen(bindPort, bindHost, () => logEvent("server_start", { host: bindHost, port: bindPort }));
+  return server;
+}

package/src/setup.js

@@ -0,0 +1,121 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { ensureApiKey, loadConfig } from "./config.js";
+import { logEvent } from "./log.js";
+
+const AERIAL_ENV_KEY = "AERIAL_API_KEY";
+
+function backupIfExists(file) {
+  if (!fs.existsSync(file)) return undefined;
+  const backup = `${file}.aerial-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+  fs.copyFileSync(file, backup);
+  return backup;
+}
+
+function ensureParent(file) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+}
+
+function setTomlString(content, key, value) {
+  const line = `${key} = "${value}"`;
+  const re = new RegExp(`^${key}\\s*=.*$`, "m");
+  return re.test(content) ? content.replace(re, line) : `${content.trimEnd()}\n${line}\n`;
+}
+
+function upsertTomlSection(content, section, values) {
+  const heading = `[${section}]`;
+  const lines = Object.entries(values).map(([key, value]) => `${key} = "${value}"`).join("\n");
+  const block = `${heading}\n${lines}\n`;
+  const source = content.split(/\r?\n/);
+  const start = source.findIndex((line) => line.trim() === heading);
+  if (start === -1) return `${content.trimEnd()}\n\n${block}`;
+  let end = source.length;
+  for (let i = start + 1; i < source.length; i += 1) {
+    if (/^\s*\[.*\]\s*$/.test(source[i])) {
+      end = i;
+      break;
+    }
+  }
+  source.splice(start, end - start, ...block.trimEnd().split("\n"));
+  return `${source.join("\n").trimEnd()}\n`;
+}
+
+function persistUserEnv(name, value) {
+  process.env[name] = value;
+  if (process.env.AERIAL_SKIP_ENV_PERSIST === "1") return { persisted: false, reason: "skipped" };
+  if (process.platform === "win32") {
+    const escaped = String(value).replace(/'/g, "''");
+    const command = `[Environment]::SetEnvironmentVariable('${name}', '${escaped}', 'User')`;
+    const { status, error } = spawnSync("powershell.exe", ["-NoProfile", "-Command", command], { stdio: "ignore" });
+    if (status === 0) return { persisted: true, target: "user" };
+    return { persisted: false, reason: error?.message || `powershell exited ${status}` };
+  }
+  return { persisted: false, reason: "unsupported_platform" };
+}
+
+function ensureClientApiKeyEnv() {
+  const result = ensureApiKey();
+  if (!result.apiKey) return { ...result, env: { name: AERIAL_ENV_KEY, persisted: false, reason: "raw_key_unavailable" } };
+  return { ...result, env: { name: AERIAL_ENV_KEY, ...persistUserEnv(AERIAL_ENV_KEY, result.apiKey) } };
+}
+
+function claudeEnvForAerial(currentEnv, config) {
+  const {
+    ANTHROPIC_API_KEY,
+    ANTHROPIC_AUTH_TOKEN,
+    ANTHROPIC_MODEL,
+    ANTHROPIC_DEFAULT_SONNET_MODEL,
+    ANTHROPIC_DEFAULT_OPUS_MODEL,
+    ...rest
+  } = currentEnv || {};
+  return {
+    ...rest,
+    ANTHROPIC_BASE_URL: `http://${config.host}:${config.port}`,
+    CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: "1"
+  };
+}
+
+export function setupCodex({ model } = {}) {
+  const apiKey = ensureClientApiKeyEnv();
+  const config = loadConfig();
+  const selectedModel = model || config.defaultModel || "gpt-4.1";
+  const file = path.join(os.homedir(), ".codex", "config.toml");
+  ensureParent(file);
+  const backup = backupIfExists(file);
+  let content = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  content = setTomlString(content, "model_provider", "aerial");
+  content = setTomlString(content, "model", selectedModel);
+  content = upsertTomlSection(content, "model_providers.aerial", {
+    name: "Aerial Copilot Local",
+    base_url: `http://${config.host}:${config.port}/v1`,
+    wire_api: "responses",
+    env_key: AERIAL_ENV_KEY
+  });
+  content = upsertTomlSection(content, "profiles.aerial", { model_provider: "aerial", model: selectedModel });
+  fs.writeFileSync(file, content, "utf8");
+  logEvent("setup_write", { target: "codex", file, backup, env: apiKey.env });
+  return { file, backup, model: selectedModel, env: apiKey.env };
+}
+
+export function setupClaude({ model } = {}) {
+  ensureApiKey();
+  const config = loadConfig();
+  const selectedModel = model || config.defaultModel;
+  const dir = path.join(os.homedir(), ".claude");
+  const file = path.join(dir, "settings.json");
+  ensureParent(file);
+  const backup = backupIfExists(file);
+  const current = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : {};
+  const next = {
+    ...current,
+    apiKeyHelper: "aerial key print",
+    env: claudeEnvForAerial(current.env, config)
+  };
+  if (selectedModel) next.model = selectedModel;
+  fs.writeFileSync(file, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+  logEvent("setup_write", { target: "claude", file, backup, model: selectedModel });
+  return { file, backup, model: selectedModel };
+}
+

package/src/version.js

@@ -0,0 +1,19 @@
+import fs from "node:fs";
+
+const PACKAGE_JSON_URL = new URL("../package.json", import.meta.url);
+
+export function readPackageVersion(packageJsonUrl = PACKAGE_JSON_URL) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(packageJsonUrl, "utf8"));
+    if (typeof pkg.version === "string" && pkg.version.length > 0) return pkg.version;
+    throw new Error("missing version field");
+  } catch (error) {
+    const reason = error?.message || String(error);
+    console.warn(`aerial: cannot read package version (${reason}); reporting "unknown"`);
+    return "unknown";
+  }
+}
+
+export function printVersion(packageJsonUrl = PACKAGE_JSON_URL) {
+  console.log(readPackageVersion(packageJsonUrl));
+}