@olares/lares-core 0.15.0

package/voice/client.js

@@ -0,0 +1,90 @@
+import { createSnapshotStore } from "../tools/async.js";
+
+export const API = "/api/lares/voice";
+
+const settings = createSnapshotStore();
+
+export function rememberedVoiceSettings() {
+  return settings.peek();
+}
+
+export async function loadVoiceSettings(options = {}) {
+  const query = options.force ? "?refresh=1" : "";
+  return settings.load(async () => {
+    const [config, status, models] = await Promise.all([
+      getJson("/config"),
+      getJson(`/status${query}`),
+      getJson(`/models${query}`),
+    ]);
+    return {
+      config,
+      status,
+      sttModels: Array.isArray(models.stt) ? models.stt : [],
+    };
+  }, options);
+}
+
+export async function saveVoiceSettings(patch) {
+  const res = await fetch(`${API}/config`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(patch),
+  });
+  if (!res.ok) throw new Error(String(res.status));
+  return loadVoiceSettings({ force: true });
+}
+
+export class TranscriptQueue {
+  constructor() {
+    this.pending = null;
+  }
+
+  apply(text, ready, draft, setDraft) {
+    if (!text) return;
+    if (ready) setDraft(mergeTranscript(draft, text));
+    else this.pending = text;
+  }
+
+  flush(ready, draft, setDraft) {
+    if (!ready || this.pending === null) return;
+    const text = this.pending;
+    this.pending = null;
+    setDraft(mergeTranscript(draft, text));
+  }
+}
+
+export function mergeTranscript(draft, transcript) {
+  const base = String(draft ?? "").replace(/\s+$/, "");
+  const text = String(transcript ?? "").trim();
+  if (!text) return String(draft ?? "");
+  if (!base) return text;
+  if (/^[,.;!?，。；！？、]/.test(text)) return `${base}${text}`;
+  return `${base} ${text}`;
+}
+
+export async function postTranscribe(blob, language, signal, options = {}) {
+  const query = language ? `?language=${encodeURIComponent(language)}` : "";
+  const base = String(options.baseUrl ?? API).replace(/\/$/, "");
+  const res = await fetch(`${base}/transcribe${query}`, {
+    method: "POST",
+    headers: { "content-type": blob.type || "audio/webm" },
+    body: blob,
+    signal,
+  });
+  if (!res.ok) {
+    let code = "voice_failed";
+    try {
+      code = (await res.json())?.error?.code ?? code;
+    } catch {
+      /* keep default */
+    }
+    throw new Error(code);
+  }
+  return String((await res.json())?.text ?? "").trim();
+}
+
+export async function getJson(path) {
+  const res = await fetch(`${API}${path}`);
+  if (!res.ok) throw new Error(`${path} → ${res.status}`);
+  return res.json();
+}

package/voice/config.js

@@ -0,0 +1,59 @@
+import { readJsonFile, writeJsonFile } from "../tools/json-file.js";
+import { dshPluginConfigPath } from "../workspace/home.js";
+import { STT_LANGUAGE_CHOICES } from "./languages.js";
+
+export { STT_LANGUAGE_CHOICES, VOICE_AUTO, voiceMenuValue, voiceValueFromMenu } from "./languages.js";
+
+const DEFAULTS = {
+  model: "",
+  language: "",
+};
+
+const WRITABLE = new Set(Object.keys(DEFAULTS));
+const SUPPORTED_LANGUAGES = new Set(["", ...STT_LANGUAGE_CHOICES.map((item) => item.id)]);
+const SAFE_MODEL = /^[^\u0000-\u001f\u007f]{0,512}$/;
+
+function invalid(message) {
+  throw Object.assign(new Error(message), { code: "voice_config_invalid", status: 400 });
+}
+
+/** @param {unknown} raw @returns {Partial<typeof DEFAULTS>} */
+export function validateConfigPatch(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) invalid("config patch must be an object");
+  const patch = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (!WRITABLE.has(key)) invalid(`unknown voice setting: ${key}`);
+    if (typeof value !== "string") invalid(`${key} must be a string`);
+    const normalized = value.trim();
+    if (key === "model" && !SAFE_MODEL.test(normalized)) invalid("invalid voice model");
+    if (key === "language" && !SUPPORTED_LANGUAGES.has(normalized)) invalid("unsupported recognition language");
+    patch[key] = normalized;
+  }
+  return patch;
+}
+
+function configPath() {
+  return dshPluginConfigPath("voice-input");
+}
+
+/** @returns {typeof DEFAULTS} */
+export function readConfig() {
+  const stored = readJsonFile(configPath());
+  const merged = { ...DEFAULTS };
+  const model = typeof stored?.model === "string" ? stored.model.trim() : "";
+  const language = typeof stored?.language === "string" ? stored.language.trim() : "";
+  if (SAFE_MODEL.test(model)) merged.model = model;
+  if (SUPPORTED_LANGUAGES.has(language)) merged.language = language;
+  return merged;
+}
+
+/** @param {Record<string, unknown>} patch @returns {typeof DEFAULTS} */
+export function writeConfig(patch) {
+  const next = readConfig();
+  for (const [key, value] of Object.entries(validateConfigPatch(patch))) {
+    next[key] = value;
+  }
+  const path = configPath();
+  writeJsonFile(path, next);
+  return next;
+}

package/voice/languages.js

@@ -0,0 +1,29 @@
+export const VOICE_AUTO = "auto";
+export const STT_LANGUAGE_CHOICES = [
+  { id: "zh", label: "中文" },
+  { id: "en", label: "English" },
+  { id: "ja", label: "日本語" },
+  { id: "ko", label: "한국어" },
+];
+
+export function voiceMenuValue(stored) {
+  return stored || VOICE_AUTO;
+}
+
+export function voiceValueFromMenu(id) {
+  return id === VOICE_AUTO ? "" : id;
+}
+
+export const EMPTY_VOICE_CONFIG = { model: "", language: "" };
+
+export function voiceLanguageItems(autoLabel) {
+  return [{ id: VOICE_AUTO, label: autoLabel }, ...STT_LANGUAGE_CHOICES];
+}
+
+export function voiceModelItems(sttIds, autoLabel) {
+  return [{ id: VOICE_AUTO, label: autoLabel }, ...sttIds.map((id) => ({ id, label: id }))];
+}
+
+export function voiceStatusReady(status) {
+  return Boolean(status?.modelAvailable);
+}

package/voice/recorder.js

@@ -0,0 +1,43 @@
+const MIME_CANDIDATES = [
+  "audio/webm;codecs=opus",
+  "audio/webm",
+  "audio/ogg;codecs=opus",
+  "audio/mp4",
+];
+
+/** Below this the blob is container header only. */
+export const MIN_RECORDING_MS = 700;
+export const MIN_RECORDING_BYTES = 1024;
+
+export const RECORDING_AUDIO = {
+  channelCount: 1,
+  echoCancellation: false,
+  noiseSuppression: false,
+  autoGainControl: true,
+};
+
+export function isComposerVoiceReady(phase, setDraft) {
+  return phase === "plain" && typeof setDraft === "function";
+}
+
+export function isRecordingTooShort(durationMs, byteSize) {
+  return durationMs < MIN_RECORDING_MS || byteSize < MIN_RECORDING_BYTES;
+}
+
+export function pickRecordingMime(recorder = globalThis.MediaRecorder) {
+  if (typeof recorder === "undefined" || recorder === undefined) return "";
+  for (const type of MIME_CANDIDATES) {
+    try {
+      if (recorder.isTypeSupported(type)) return type;
+    } catch {
+      return "";
+    }
+  }
+  return "";
+}
+
+export function formatElapsed(ms) {
+  const total = Math.max(0, Math.floor(ms / 1000));
+  const s = String(total % 60).padStart(2, "0");
+  return `${Math.floor(total / 60)}:${s}`;
+}

package/voice/service.js

@@ -0,0 +1,83 @@
+import { readConfig, validateConfigPatch, writeConfig } from "./config.js";
+import {
+  STT_MAX_AUDIO_BYTES,
+  VoiceError,
+  audioFilenameForContentType,
+  listModels,
+  pickSttModelId,
+  resolveSttModel,
+  sttModelIds,
+  transcribe,
+} from "../router/stt.js";
+
+export { STT_MAX_AUDIO_BYTES };
+
+export async function voiceStatusPayload(options) {
+  const config = readConfig();
+  let modelAvailable = false;
+  let resolvedModel = config.model;
+  try {
+    const models = await listModels(options);
+    resolvedModel = pickSttModelId(models, config.model) ?? "";
+    modelAvailable = Boolean(resolvedModel);
+  } catch {
+    modelAvailable = false;
+  }
+  return {
+    ok: modelAvailable,
+    model: resolvedModel,
+    modelAvailable,
+    language: config.language,
+  };
+}
+
+export async function voiceModelsPayload(options) {
+  const models = await listModels(options);
+  const ids = models.map((model) => model.id);
+  const stt = sttModelIds(models);
+  const selected = pickSttModelId(models, readConfig().model);
+  return { models: ids, stt, selected };
+}
+
+export async function saveVoiceConfig(body) {
+  const patch = validateConfigPatch(body);
+  if (patch.model) {
+    const available = sttModelIds(await listModels());
+    if (!available.includes(patch.model)) {
+      throw new VoiceError("voice_model_unavailable", 400, "selected voice model is not available");
+    }
+  }
+  return writeConfig(patch);
+}
+
+export function languageForTranscribe(requestedLanguage, configLanguage) {
+  if (requestedLanguage === null) return configLanguage || undefined;
+  return validateConfigPatch({ language: requestedLanguage }).language || undefined;
+}
+
+export async function transcribeFromHttp({ languageParam, contentType, bytes }) {
+  const config = readConfig();
+  const text = await transcribeAudio({
+    bytes,
+    contentType,
+    language: languageForTranscribe(languageParam, config.language),
+    preferred: config.model,
+  });
+  return { text };
+}
+
+export async function transcribeAudio({ bytes, contentType, language, preferred }) {
+  const model = await resolveSttModel(preferred);
+  if (!model) {
+    throw new VoiceError("voice_model_unavailable", 503, "no voice model available in the Router catalog");
+  }
+  if (bytes.length === 0) throw new VoiceError("voice_audio_unreadable", 400, "audio content is empty");
+  return transcribe({
+    bytes,
+    filename: audioFilenameForContentType(contentType),
+    contentType,
+    model,
+    language,
+    preferred,
+  });
+}

package/workspace/env.js

@@ -0,0 +1,13 @@
+/** @param {NodeJS.ProcessEnv} [env] */
+export function workspaceRootFromEnv(env = process.env) {
+  const value = env.DSH_CWD ?? env.LARES_WORKSPACE;
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+export function workspaceRootFromSession(exec, env = process.env) {
+  const cwd = exec?.agent?.session?.header?.cwd ?? workspaceRootFromEnv(env);
+  if (cwd === null || cwd === undefined || cwd === "") {
+    throw new Error("no session workspace to fetch into");
+  }
+  return cwd;
+}

package/workspace/home.js

@@ -0,0 +1,9 @@
+import { join } from "node:path";
+
+export function dshHome(env = process.env) {
+  return env.DSH_HOME?.trim() || "/data/lares/dsh-home";
+}
+
+export function dshPluginConfigPath(plugin, env = process.env) {
+  return join(dshHome(env), plugin, "config.json");
+}

package/workspace/path.js

@@ -0,0 +1,80 @@
+import { lstatSync } from "node:fs";
+import { mkdir, realpath, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { HttpError } from "../tools/http.js";
+
+export function isInsideWorkspace(root, target) {
+  const path = relative(root, target);
+  return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path));
+}
+
+export async function resolveWorkspaceRoot(workspacePath) {
+  return realpath(workspacePath).catch(() => {
+    throw new HttpError("workspace_unavailable", 409, "session workspace is unavailable");
+  });
+}
+
+export function workspaceCandidate(root, requestedPath) {
+  const candidate = resolve(root, requestedPath);
+  if (!isInsideWorkspace(root, candidate)) {
+    throw new HttpError("path_forbidden", 403, "path leaves the session workspace");
+  }
+  return candidate;
+}
+
+export async function resolveExistingWorkspacePath(root, candidate) {
+  const absolutePath = await realpath(candidate).catch(() => {
+    throw new HttpError("file_not_found", 404, "file was not found");
+  });
+  if (!isInsideWorkspace(root, absolutePath)) {
+    throw new HttpError("path_forbidden", 403, "path leaves the session workspace");
+  }
+  return absolutePath;
+}
+
+export async function ensureWorkspaceDirectory(workspacePath, parts) {
+  const root = await resolveWorkspaceRoot(workspacePath);
+  let current = root;
+  for (const part of parts) {
+    const candidate = workspaceCandidate(current, part);
+    await mkdir(candidate).catch((error) => {
+      if (error?.code !== "EEXIST") throw error;
+    });
+    current = await realpath(candidate).catch(() => {
+      throw new HttpError("workspace_unavailable", 409, "workspace directory is unavailable");
+    });
+    if (!isInsideWorkspace(root, current)) {
+      throw new HttpError("path_forbidden", 403, "workspace directory leaves the session workspace");
+    }
+    const info = await stat(current);
+    if (!info.isDirectory()) {
+      throw new HttpError("workspace_unavailable", 409, "workspace path is not a directory");
+    }
+  }
+  return { root, directory: current };
+}
+
+/**
+ * Absolute path a workspace write will occupy. Refuses to clobber a symlink
+ * or non-file; an existing regular file needs `overwrite`.
+ */
+export async function prepareWorkspaceTarget(root, destination, overwrite) {
+  const segments = destination.split("/");
+  const { directory } = await ensureWorkspaceDirectory(root, segments.slice(0, -1));
+  const absolutePath = workspaceCandidate(directory, segments.at(-1));
+  let current = null;
+  try {
+    current = lstatSync(absolutePath);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  if (current !== null) {
+    if (!overwrite) {
+      throw new Error(`${destination} already exists; pass overwrite or choose another destination`);
+    }
+    if (current.isSymbolicLink() || !current.isFile()) {
+      throw new Error(`${destination} cannot overwrite a symlink or non-regular file`);
+    }
+  }
+  return absolutePath;
+}

package/workspace/seed.js

@@ -0,0 +1,13 @@
+import { mkdirSync } from "node:fs";
+
+export const DEFAULT_WORKSPACE_TITLE = "Default";
+
+/**
+ * @param {{ create: (path: string, title?: string) => Promise<{ id: string, path: string, title: string }> }} registry
+ * @param {string} workspacePath
+ * @param {string} [title]
+ */
+export async function seedDefaultWorkspace(registry, workspacePath, title = DEFAULT_WORKSPACE_TITLE) {
+  mkdirSync(workspacePath, { recursive: true });
+  return registry.create(workspacePath, title);
+}

package/workspace/session.js

@@ -0,0 +1,42 @@
+import { HttpError } from "../tools/http.js";
+import { resolveWorkspaceRoot } from "./path.js";
+
+/**
+ * The directory a session owns is its own header `cwd`. Registry membership is
+ * dsh's grouping account instead: it is written only when the client names a
+ * workspaceId while creating the session, so an ordinary new chat is ungrouped
+ * and has no membership at all while still working in a real directory.
+ *
+ * The registry stays in the lookup as the boundary of what this deployment
+ * serves — a cwd that is not a registered workspace path is refused, so a
+ * session created with an arbitrary cwd cannot read outside those directories.
+ *
+ * @param ctx - Cordis context carrying `workspaceRegistry` and `sessionPersistence`.
+ * @param sessionId - Session the request claims to act for.
+ */
+export async function resolveSessionWorkspace(ctx, sessionId) {
+  if (typeof sessionId !== "string" || !sessionId) {
+    throw new HttpError("session_required", 400, "session id is required");
+  }
+  const cwd = await sessionCwd(ctx, sessionId);
+  if (cwd === null) {
+    throw new HttpError("workspace_not_found", 404, "session workspace was not found");
+  }
+  const workspace = await ctx.workspaceRegistry.resolveByPath(await resolveWorkspaceRoot(cwd));
+  if (workspace === undefined) {
+    throw new HttpError("workspace_not_found", 404, "session workspace was not found");
+  }
+  if ((await workspace.status()) !== "ok") {
+    throw new HttpError("workspace_unavailable", 409, "session workspace is unavailable");
+  }
+  return workspace;
+}
+
+/** Live sessions answer without touching storage; anything else needs the log header. */
+async function sessionCwd(ctx, sessionId) {
+  const live = ctx.get("sessions")?.get(sessionId);
+  if (typeof live?.header?.cwd === "string") return live.header.cwd;
+  const headers = await ctx.sessionPersistence.list();
+  const cwd = headers.find((header) => String(header.id) === sessionId)?.cwd;
+  return typeof cwd === "string" ? cwd : null;
+}