@olares/lares-core 0.15.0

package/router/shim.js

@@ -0,0 +1,134 @@
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { readBody, sendError } from "../tools/http.js";
+import { carriesWebpImage, transcodeWebpImages } from "../media/router-images.js";
+import { routerAuthHeaders, routerGatewayUrl } from "./gateway.js";
+import { STT_MAX_AUDIO_BYTES } from "./stt.js";
+
+export const SHIM_PATH = "/llm/v1";
+export const SHIM_CHAT_TIMEOUT_MS = 120_000;
+export const SHIM_AUDIO_TIMEOUT_MS = 180_000;
+export const SHIM_CHAT_MAX_BYTES = 16 * 1024 * 1024;
+
+const DROPPED_REQ = new Set([
+  "authorization",
+  "connection",
+  "content-length",
+  "host",
+  "keep-alive",
+  "transfer-encoding",
+  "upgrade",
+  "x-olares-app-id",
+  "x-caller-appid",
+]);
+
+const DROPPED_RES = new Set(["connection", "content-encoding", "content-length", "transfer-encoding"]);
+
+export function llmShimSuffix(pathname) {
+  return pathname.replace(/^\/llm\/v1\/?/, "").replace(/^\/+/, "");
+}
+
+export function isAudioShimPath(suffix) {
+  return /(^|\/)audio(\/|$)/.test(suffix);
+}
+
+export function shimBudget(suffix) {
+  const audio = isAudioShimPath(suffix);
+  return {
+    audio,
+    timeoutMs: audio ? SHIM_AUDIO_TIMEOUT_MS : SHIM_CHAT_TIMEOUT_MS,
+    maxBytes: audio ? STT_MAX_AUDIO_BYTES : SHIM_CHAT_MAX_BYTES,
+    tooLargeMessage: audio ? "audio exceeds 25MB" : "LLM request exceeds 16MB",
+  };
+}
+
+export function shimRequestHeaders(incoming, env = process.env) {
+  const headers = {};
+  for (const [key, value] of Object.entries(incoming)) {
+    if (value == null || DROPPED_REQ.has(key.toLowerCase())) continue;
+    headers[key] = Array.isArray(value) ? value.join(",") : value;
+  }
+  Object.assign(
+    headers,
+    routerAuthHeaders(env.LARES_ROUTER_API_KEY?.trim() || null, env.OLARES_APP_ID?.trim() || "lares"),
+  );
+  return headers;
+}
+
+export function shimResponseHeaders(incoming) {
+  const headers = {};
+  for (const [key, value] of Object.entries(incoming)) {
+    if (value == null || DROPPED_RES.has(key.toLowerCase())) continue;
+    headers[key] = value;
+  }
+  return headers;
+}
+
+export function healthPayload(env = process.env) {
+  return {
+    ok: true,
+    app: "lares",
+    kernel: "dsh-web",
+    routerUrl: routerGatewayUrl(env),
+    olaresAppId: env.OLARES_APP_ID ?? "lares",
+    hasRouterKey: Boolean(env.LARES_ROUTER_API_KEY?.trim()),
+  };
+}
+
+export function proxyToRouter(req, res, env = process.env) {
+  const routerUrl = routerGatewayUrl(env);
+  const rawUrl = req.url ?? "/";
+  const u = new URL(rawUrl, "http://x");
+  const suffix = llmShimSuffix(u.pathname);
+  const target = new URL(`${routerUrl}/${suffix}${u.search}`);
+  const budget = shimBudget(suffix);
+  const headers = shimRequestHeaders(req.headers, env);
+  const transport = target.protocol === "https:" ? httpsRequest : httpRequest;
+  const method = (req.method ?? "GET").toUpperCase();
+
+  const run = async () => {
+    let body;
+    if (method !== "GET" && method !== "HEAD") {
+      body = await readBody(req, {
+        maxBytes: budget.maxBytes,
+        message: budget.tooLargeMessage,
+      });
+      if (!budget.audio && carriesWebpImage(body)) body = await transcodeWebpImages(body);
+      headers["content-length"] = String(body.length);
+    }
+
+    const upstream = transport(
+      target,
+      { method, headers, timeout: budget.timeoutMs },
+      (up) => {
+        res.writeHead(up.statusCode ?? 502, shimResponseHeaders(up.headers));
+        up.pipe(res);
+      },
+    );
+    upstream.on("error", (err) => {
+      if (res.headersSent) {
+        res.destroy();
+        return;
+      }
+      res.writeHead(502, { "content-type": "application/json" });
+      res.end(
+        JSON.stringify({
+          error: {
+            type: "upstream_unreachable",
+            message: `Cannot reach Router at ${routerUrl}: ${err.message}`,
+          },
+        }),
+      );
+    });
+    if (body) upstream.end(body);
+    else upstream.end();
+  };
+
+  void run().catch((err) => {
+    if (res.headersSent) {
+      res.destroy();
+      return;
+    }
+    sendError(res, err, "llm_proxy_failed");
+  });
+}

package/router/stt.js

@@ -0,0 +1,200 @@
+import { randomBytes } from "node:crypto";
+import { createInFlightCoalescer } from "../tools/async.js";
+import { routerCatalogRows } from "./catalog.js";
+import { routerShimBaseUrl } from "./gateway.js";
+
+const STT_HINTS = /whisper|\bstt\b|\basr\b|transcri/i;
+const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
+const UNDECODABLE_HINTS = [
+  "end of file",
+  "format not recognised",
+  "format not recognized",
+  "invalid data found",
+  "moov atom not found",
+  "unknown file extension",
+  "failed to load audio",
+];
+
+export class VoiceError extends Error {
+  constructor(code, status, message) {
+    super(message);
+    this.code = code;
+    this.status = status;
+  }
+}
+
+export function sttModelIds(models) {
+  return models
+    .filter((model) => model.mode === "audio" && STT_HINTS.test(model.id))
+    .map((model) => model.id);
+}
+
+export function pickSttModelId(models, preferred) {
+  const stt = sttModelIds(models);
+  const want = (preferred ?? "").trim();
+  if (want && stt.includes(want)) return want;
+  return stt[0] ?? null;
+}
+
+export function classifyFailure(status, body) {
+  const lowered = body.toLowerCase();
+  if (UNDECODABLE_HINTS.some((hint) => lowered.includes(hint))) return "voice_audio_unreadable";
+  if (status === 400 || status === 415 || status === 422) return "voice_audio_unreadable";
+  if (status === 404) return "voice_model_unavailable";
+  return "voice_failed";
+}
+
+export function retryable(status) {
+  return RETRYABLE_STATUS.has(status);
+}
+
+export const STT_MAX_AUDIO_BYTES = 25 * 1024 * 1024;
+
+const AUDIO_EXTENSIONS = {
+  "audio/webm": "webm",
+  "audio/ogg": "ogg",
+  "audio/mp4": "mp4",
+  "audio/mpeg": "mp3",
+  "audio/aac": "aac",
+  "audio/wav": "wav",
+  "audio/wave": "wav",
+  "audio/x-wav": "wav",
+};
+
+export function audioFilenameForContentType(contentType) {
+  const base = String(contentType ?? "").split(";", 1)[0].trim().toLowerCase();
+  return `voice.${AUDIO_EXTENSIONS[base] ?? "webm"}`;
+}
+
+const REQUEST_TIMEOUT_MS = 180_000;
+const CATALOG_TIMEOUT_MS = 15_000;
+const RETRY_BACKOFF_MS = [1_000, 3_000];
+const RESOLVED_TTL_MS = 120_000;
+
+const coalesceCatalog = createInFlightCoalescer();
+/** @type {{ expires: number, rows: { id: string, mode: string | null }[] } | null} */
+let catalog = null;
+
+async function fetchCatalog() {
+  const res = await fetch(`${routerShimBaseUrl()}/models`, {
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(CATALOG_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new VoiceError("voice_model_unavailable", 503, `Router /models returned ${res.status}`);
+  const rows = routerCatalogRows(await res.json()).map(({ id, mode }) => ({ id, mode }));
+  catalog = { expires: Date.now() + RESOLVED_TTL_MS, rows };
+  return rows;
+}
+
+/** @returns {Promise<{ id: string, mode: string | null }[]>} */
+export async function listModels(options) {
+  if (!options?.refresh && catalog && catalog.expires > Date.now()) return catalog.rows;
+  if (options?.refresh) return fetchCatalog();
+  return coalesceCatalog(fetchCatalog);
+}
+
+/** @returns {Promise<string[]>} */
+export async function listModelIds() {
+  return (await listModels()).map((model) => model.id);
+}
+
+/** @type {{ expires: number, id: string, preferred: string } | null} */
+let resolved = null;
+
+/** Cached STT model id (short TTL). @param {string} [preferred] */
+export async function resolveSttModel(preferred, options) {
+  const want = (preferred ?? "").trim();
+  if (
+    !options?.refresh
+    && resolved
+    && resolved.expires > Date.now()
+    && resolved.preferred === want
+  ) {
+    return resolved.id;
+  }
+  const id = pickSttModelId(await listModels(options), want);
+  resolved = id ? { expires: Date.now() + RESOLVED_TTL_MS, id, preferred: want } : null;
+  return id;
+}
+
+export function forgetSttModel() {
+  resolved = null;
+  catalog = null;
+}
+
+/** @param {Record<string, string>} fields @param {{ filename: string, contentType: string, bytes: Buffer }} file */
+function multipartBody(fields, file) {
+  const boundary = `----lares-voice-${randomBytes(12).toString("hex")}`;
+  const parts = [];
+  for (const [name, value] of Object.entries(fields)) {
+    parts.push(
+      Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`),
+    );
+  }
+  parts.push(
+    Buffer.from(
+      `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${file.filename}"\r\n`
+      + `Content-Type: ${file.contentType}\r\n\r\n`,
+    ),
+  );
+  parts.push(file.bytes);
+  parts.push(Buffer.from(`\r\n--${boundary}--\r\n`));
+  return { boundary, body: Buffer.concat(parts) };
+}
+
+/** @param {Response} res */
+async function readTranscript(res) {
+  const text = await res.text();
+  try {
+    const payload = JSON.parse(text);
+    if (payload && typeof payload === "object" && payload.text != null) return String(payload.text).trim();
+    if (typeof payload === "string") return payload.trim();
+  } catch {
+    if (text.trim()) return text.trim();
+  }
+  throw new VoiceError("voice_failed", 502, "invalid transcription response");
+}
+
+/**
+ * @param {{ bytes: Buffer, filename: string, contentType: string, model: string, language?: string, prompt?: string, preferred?: string }} take
+ * @returns {Promise<string>}
+ */
+export async function transcribe(take) {
+  let model = take.model;
+  for (let attempt = 0; ; attempt += 1) {
+    const fields = { model };
+    if (take.language) fields.language = take.language;
+    if (take.prompt) fields.prompt = take.prompt;
+    const { boundary, body } = multipartBody(fields, {
+      filename: take.filename,
+      contentType: take.contentType,
+      bytes: take.bytes,
+    });
+
+    /** @type {VoiceError} */
+    let failure;
+    try {
+      const res = await fetch(`${routerShimBaseUrl()}/audio/transcriptions`, {
+        method: "POST",
+        headers: { "content-type": `multipart/form-data; boundary=${boundary}` },
+        body,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+      if (res.ok) return await readTranscript(res);
+      const text = await res.text();
+      failure = new VoiceError(classifyFailure(res.status, text), res.status, text.slice(0, 400));
+      if (!retryable(res.status)) throw failure;
+    } catch (err) {
+      if (err instanceof VoiceError) throw err;
+      const timedOut = err?.name === "TimeoutError" || err?.name === "AbortError";
+      failure = timedOut
+        ? new VoiceError("voice_timeout", 504, "transcription timed out")
+        : new VoiceError("voice_failed", 502, `router unreachable: ${err?.message ?? err}`);
+    }
+
+    if (attempt >= RETRY_BACKOFF_MS.length) throw failure;
+    await new Promise((resolve) => setTimeout(resolve, RETRY_BACKOFF_MS[attempt]));
+    const refreshed = await resolveSttModel(take.preferred, { refresh: true }).catch(() => null);
+    if (refreshed) model = refreshed;
+  }
+}

package/search/client.js

@@ -0,0 +1,38 @@
+import { createSnapshotStore } from "../tools/async.js";
+
+export const API = "/api/lares/web-search";
+
+const settings = createSnapshotStore();
+
+export function rememberedSearchSettings() {
+  return settings.peek();
+}
+
+export async function loadSearchSettings(options = {}) {
+  return settings.load(() => getJson("/config"), options);
+}
+
+export async function saveSearchDefault(id) {
+  return settings.remember(await postJson("/config/default", { defaultSearchModel: id }));
+}
+
+export async function getJson(path) {
+  const res = await fetch(`${API}${path}`);
+  if (!res.ok) throw new Error(`${path} → ${res.status}`);
+  return res.json();
+}
+
+export async function postJson(path, body) {
+  const res = await fetch(`${API}${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body ?? {}),
+  });
+  const payload = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const code = payload?.error?.code ?? String(res.status);
+    const message = payload?.error?.message ?? code;
+    throw new Error(message);
+  }
+  return payload;
+}

package/search/config.js

@@ -0,0 +1,98 @@
+import { readJsonFile, writeJsonFile } from "../tools/json-file.js";
+import { HttpError } from "../tools/http.js";
+import { dshPluginConfigPath } from "../workspace/home.js";
+import { fetchRouterSearchModels } from "../router/search.js";
+
+/** @typedef {{ defaultSearchModel: string | null }} WebSearchConfig */
+
+/** @returns {WebSearchConfig} */
+function defaults() {
+  return { defaultSearchModel: null };
+}
+
+function configPath() {
+  return dshPluginConfigPath("web-search");
+}
+
+/** @param {unknown} raw @returns {WebSearchConfig} */
+function normalize(raw) {
+  if (!raw || typeof raw !== "object") return defaults();
+  const body = /** @type {Record<string, unknown>} */ (raw);
+  const value = typeof body.defaultSearchModel === "string" ? body.defaultSearchModel.trim() : "";
+  return {
+    defaultSearchModel: value && value.length <= 512 && !/[\u0000-\u001f\u007f]/.test(value)
+      ? value
+      : null,
+  };
+}
+
+/** @returns {WebSearchConfig} */
+export function readConfig() {
+  return normalize(readJsonFile(configPath()));
+}
+
+/**
+ * @param {WebSearchConfig} config
+ * @returns {WebSearchConfig}
+ */
+function persist(config) {
+  const path = configPath();
+  const normalized = normalize(config);
+  writeJsonFile(path, normalized);
+  return normalized;
+}
+
+/**
+ * @param {string | null} id
+ * @param {{ id: string }[]} available
+ */
+export function setDefaultSearchModel(id, available) {
+  if (id === null) {
+    return persist({ defaultSearchModel: null });
+  }
+  const model = typeof id === "string" ? id.trim() : "";
+  if (
+    !model
+    || model.length > 512
+    || /[\u0000-\u001f\u007f]/.test(model)
+    || !available.some((item) => item.id === model)
+  ) {
+    throw new HttpError("not_available", 400, "search service is not available from Router");
+  }
+  return persist({ defaultSearchModel: model });
+}
+
+export async function currentSearchConfig() {
+  const searchModels = await fetchRouterSearchModels();
+  return {
+    defaultSearchModel: readConfig().defaultSearchModel,
+    searchModels,
+  };
+}
+
+export const LARES_PROVIDER_ID = "lares";
+export { SEARCH_NONE, searchDefaultReady, searchMenuValue, searchValueFromMenu } from "./menu.js";
+
+export function configuredSearchModel() {
+  return readConfig().defaultSearchModel;
+}
+
+export function defaultSearchModelFromBody(body) {
+  const id = body?.defaultSearchModel === null ? null : body?.defaultSearchModel;
+  if (id !== null && typeof id !== "string") {
+    throw new HttpError("bad_model", 400, "invalid defaultSearchModel");
+  }
+  return id;
+}
+
+export async function setDefaultSearchFromRequest(id) {
+  if (id !== null && typeof id !== "string") {
+    throw new HttpError("bad_model", 400, "invalid defaultSearchModel");
+  }
+  const searchModels = await fetchRouterSearchModels();
+  const saved = setDefaultSearchModel(id, searchModels);
+  return {
+    defaultSearchModel: saved.defaultSearchModel,
+    searchModels,
+  };
+}

package/search/menu.js

@@ -0,0 +1,22 @@
+export const SEARCH_NONE = "none";
+
+export function searchDefaultReady(models, defaultSearchModel) {
+  return Array.isArray(models) && models.some((model) => model.id === defaultSearchModel);
+}
+
+export function searchMenuValue(defaultSearchModel) {
+  return defaultSearchModel ?? SEARCH_NONE;
+}
+
+export function searchValueFromMenu(id) {
+  return id === SEARCH_NONE ? null : id;
+}
+
+export function searchModelLabel(model) {
+  return model.name || model.id;
+}
+
+export function searchSelectorItems(models, { none, empty }) {
+  if (models.length === 0) return [{ id: SEARCH_NONE, label: empty }];
+  return [{ id: SEARCH_NONE, label: none }, ...models.map((model) => ({ id: model.id, label: searchModelLabel(model) }))];
+}

package/tools/async.js

@@ -0,0 +1,34 @@
+export function createInFlightCoalescer() {
+  let current = null;
+  return (start) => {
+    if (current) return current;
+    const shared = Promise.resolve().then(start).finally(() => {
+      if (current === shared) current = null;
+    });
+    current = shared;
+    return shared;
+  };
+}
+
+/** Last successful payload survives remounts; Refresh / save pass `{ force: true }`. */
+export function createSnapshotStore() {
+  let value = null;
+  const coalesce = createInFlightCoalescer();
+  return {
+    peek() {
+      return value;
+    },
+    remember(next) {
+      value = next;
+      return next;
+    },
+    load(start, options = {}) {
+      if (!options.force && value !== null) return Promise.resolve(value);
+      return coalesce(async () => {
+        const next = await start();
+        value = next;
+        return next;
+      });
+    },
+  };
+}

package/tools/crypto-uuid.js

@@ -0,0 +1,26 @@
+/**
+ * Olares LAN zone is plain http, so browsers withhold `crypto.randomUUID`.
+ * dsh mints host-RPC ids with it; `getRandomValues` stays available.
+ */
+export const UUID_SHIM = `(function () {
+  var c = globalThis.crypto;
+  if (c === undefined || typeof c.randomUUID === "function") return;
+  c.randomUUID = function randomUUID() {
+    var bytes = c.getRandomValues(new Uint8Array(16));
+    bytes[6] = (bytes[6] & 15) | 64;
+    bytes[8] = (bytes[8] & 63) | 128;
+    var hex = Array.from(bytes, function (byte) {
+      return byte.toString(16).padStart(2, "0");
+    }).join("");
+    return hex.slice(0, 8) + "-" + hex.slice(8, 12) + "-" + hex.slice(12, 16) + "-" + hex.slice(16, 20) + "-" + hex.slice(20);
+  };
+})();`;
+
+const HEAD_OPEN = /<head[^>]*>/i;
+
+export function injectUuidShim(html) {
+  if (html.includes("data-lares-uuid-shim")) return html;
+  const tag = `<script data-lares-uuid-shim>${UUID_SHIM}</script>`;
+  const head = HEAD_OPEN.exec(html);
+  return head === null ? `${tag}${html}` : html.replace(HEAD_OPEN, `${head[0]}${tag}`);
+}

package/tools/http.js

@@ -0,0 +1,123 @@
+export class HttpError extends Error {
+  constructor(code, status, message) {
+    super(message);
+    this.code = code;
+    this.status = status;
+  }
+}
+
+export function sendJson(res, status, payload) {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify(payload));
+}
+
+/**
+ * @param {import('node:http').IncomingMessage} req
+ * @param {{ maxBytes?: number, code?: string, message?: string }} [options]
+ */
+export function readBody(req, options = {}) {
+  const maxBytes = options.maxBytes ?? 64 * 1024;
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = 0;
+    let rejected = false;
+    req.on("data", (chunk) => {
+      if (rejected) return;
+      total += chunk.length;
+      if (total > maxBytes) {
+        rejected = true;
+        reject(new HttpError(
+          options.code ?? "body_too_large",
+          413,
+          options.message ?? `body exceeds ${maxBytes} bytes`,
+        ));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (!rejected) resolve(Buffer.concat(chunks));
+    });
+    req.on("error", reject);
+  });
+}
+
+/**
+ * @param {import('node:http').IncomingMessage} req
+ * @param {{ maxBytes?: number }} [options]
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function readJsonObject(req, options) {
+  const raw = await readBody(req, options);
+  if (raw.length === 0) return {};
+  try {
+    const body = JSON.parse(raw.toString("utf8"));
+    if (body && typeof body === "object" && !Array.isArray(body)) return body;
+  } catch {
+    // The common error below is the public contract for every malformed body.
+  }
+  throw new HttpError("bad_request", 400, "invalid JSON body");
+}
+
+function errorResponse(err, fallbackCode) {
+  if (
+    err
+    && typeof err === "object"
+    && typeof err.code === "string"
+    && typeof err.status === "number"
+  ) {
+    return {
+      status: err.status >= 400 ? err.status : 500,
+      code: err.code,
+      message: err instanceof Error ? err.message : String(err),
+    };
+  }
+  return {
+    status: 500,
+    code: fallbackCode,
+    message: err instanceof Error ? err.message : String(err),
+  };
+}
+
+export function sendError(res, err, fallbackCode) {
+  const failure = errorResponse(err, fallbackCode);
+  sendJson(res, failure.status, {
+    error: { code: failure.code, message: failure.message },
+  });
+}
+
+/**
+ * @param {{
+ *   prefix: string,
+ *   routes: Record<string, Record<string, (req: any, res: any) => Promise<void> | void>>,
+ *   fallbackCode: string
+ * }} options
+ */
+export function createRouteHandler(options) {
+  return (req, res) => {
+    const method = (req.method ?? "GET").toUpperCase();
+    const suffix = new URL(req.url ?? "/", "http://x").pathname.slice(options.prefix.length) || "/";
+    const path = suffix.replace(/\/+$/, "") || "/";
+    const handlers = options.routes[path];
+    if (!handlers) {
+      sendJson(res, 404, {
+        error: { code: "not_found", message: `no route ${path}` },
+      });
+      return;
+    }
+    const route = handlers[method];
+    if (!route) {
+      sendJson(res, 405, {
+        error: { code: "method_not_allowed", message: `${method} not allowed` },
+      });
+      return;
+    }
+    Promise.resolve().then(() => route(req, res)).catch((err) => {
+      if (res.headersSent) {
+        res.destroy();
+        return;
+      }
+      sendError(res, err, options.fallbackCode);
+    });
+  };
+}

package/tools/json-file.js

@@ -0,0 +1,18 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export function readJsonFile(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeJsonFile(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, path);
+}