@olares/lares-core 0.15.0

package/larepass/mux.js

@@ -0,0 +1,194 @@
+export const MUX_PATH = "/api/events.mux";
+
+export const MUX_FETCH_HEADERS = {
+  accept: "text/event-stream",
+  "cache-control": "no-cache",
+  "accept-encoding": "identity",
+};
+
+export function muxWsUrl(httpUrl, origin = "http://localhost") {
+  const url = new URL(httpUrl, origin);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return url.href;
+}
+
+export function splitSseBlocks(buffer) {
+  const blocks = [];
+  let rest = String(buffer ?? "").replace(/\r\n/g, "\n");
+  let boundary = rest.indexOf("\n\n");
+  while (boundary !== -1) {
+    blocks.push(rest.slice(0, boundary));
+    rest = rest.slice(boundary + 2);
+    boundary = rest.indexOf("\n\n");
+  }
+  return { blocks, rest };
+}
+
+export function sseData(block) {
+  return String(block ?? "")
+    .split("\n")
+    .filter((line) => line.startsWith("data: "))
+    .map((line) => line.slice(6))
+    .join("");
+}
+
+export function muxPayload(envelope) {
+  if (!envelope || typeof envelope !== "object") return null;
+  return envelope.type === "server-request" ? envelope.payload : envelope;
+}
+
+export function muxEventFrame(envelope) {
+  const frame = muxPayload(envelope);
+  if (frame?.type !== "session/event" || !frame.event) return null;
+  return {
+    sessionId: frame.sessionId || "",
+    event: frame.view ? { ...frame.event, view: frame.view } : frame.event,
+  };
+}
+
+/**
+ * Mux carries session events and answerable waits on the same stream.
+ * `question/requested` is replayed on every open; dropping it leaves the turn
+ * running with no way to answer.
+ */
+export function classifyMuxEnvelope(envelope) {
+  const frame = muxPayload(envelope);
+  if (!frame || typeof frame !== "object") return null;
+  const sessionId = frame.sessionId || "";
+  const rpcId = typeof envelope?.rpcId === "string" ? envelope.rpcId : "";
+  if (frame.type === "session/event" && frame.event) {
+    return {
+      kind: "event",
+      sessionId,
+      event: frame.view ? { ...frame.event, view: frame.view } : frame.event,
+    };
+  }
+  if (frame.type === "question/requested") {
+    return {
+      kind: "question",
+      sessionId,
+      rpcId,
+      questions: Array.isArray(frame.questions) ? frame.questions : [],
+    };
+  }
+  if (frame.type === "question/resolved") {
+    return {
+      kind: "question-resolved",
+      sessionId,
+      rpcId: frame.questionRpcId || rpcId,
+      outcome: frame.outcome,
+    };
+  }
+  return null;
+}
+
+export function muxSessionEvent(envelope, sessionId) {
+  const frame = muxEventFrame(envelope);
+  if (!frame) return null;
+  if (sessionId && frame.sessionId !== sessionId) return null;
+  return frame.event;
+}
+
+function decodeChunk(chunk, decoder) {
+  if (typeof chunk === "string") return chunk;
+  return decoder.decode(chunk, { stream: true });
+}
+
+export async function* iterateSseJson(chunks) {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for await (const chunk of chunks) {
+    buffer += decodeChunk(chunk, decoder);
+    const { blocks, rest } = splitSseBlocks(buffer);
+    buffer = rest;
+    for (const block of blocks) {
+      const data = sseData(block);
+      if (!data) continue;
+      try {
+        yield JSON.parse(data);
+      } catch {
+        // one corrupt frame must not kill the stream
+      }
+    }
+  }
+}
+
+export async function* bytesOf(body) {
+  if (!body || typeof body.getReader !== "function") return;
+  const reader = body.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      if (value) yield value;
+    }
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      // already released
+    }
+  }
+}
+
+export async function* iterateWsJson(socket) {
+  const inbox = [];
+  let wake;
+  const enqueue = (item) => {
+    inbox.push(item);
+    wake?.();
+    wake = undefined;
+  };
+  const onMessage = (event) => {
+    const data = event?.data;
+    if (typeof data !== "string") return;
+    try {
+      enqueue(JSON.parse(data));
+    } catch {
+      // one corrupt frame must not kill the stream
+    }
+  };
+  const onClose = () => enqueue(null);
+  socket.addEventListener("message", onMessage);
+  socket.addEventListener("close", onClose, { once: true });
+  try {
+    while (true) {
+      while (inbox.length > 0) {
+        const item = inbox.shift();
+        if (item === null) return;
+        yield item;
+      }
+      await new Promise((resolve) => {
+        wake = resolve;
+      });
+    }
+  } finally {
+    socket.removeEventListener("message", onMessage);
+    socket.removeEventListener("close", onClose);
+  }
+}
+
+export async function* consumeMuxInbox(source) {
+  const envelopes = typeof source?.getReader === "function"
+    ? iterateSseJson(bytesOf(source))
+    : iterateWsJson(source);
+  for await (const envelope of envelopes) {
+    const item = classifyMuxEnvelope(envelope);
+    if (item) yield item;
+  }
+}
+
+export async function* consumeMuxFrames(source) {
+  for await (const item of consumeMuxInbox(source)) {
+    if (item.kind === "event") yield { sessionId: item.sessionId, event: item.event };
+  }
+}
+
+export async function* consumeMux(source, sessionId) {
+  const currentId = () => (typeof sessionId === "function" ? sessionId() : sessionId);
+  for await (const frame of consumeMuxFrames(source)) {
+    const want = currentId();
+    if (want && frame.sessionId !== want) continue;
+    yield frame.event;
+  }
+}

package/larepass/questions.js

@@ -0,0 +1,16 @@
+export function parseAskUserQuestions(argsRaw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(argsRaw ?? ""));
+  } catch {
+    return [];
+  }
+  const list = Array.isArray(parsed?.questions) ? parsed.questions : [];
+  return list.filter((item) => item && typeof item.id === "string" && typeof item.question === "string");
+}
+
+export function singleSelectAnswer(questionId, label) {
+  return {
+    answers: [{ id: String(questionId), selected: [String(label)] }],
+  };
+}

package/larepass/rpc.js

@@ -0,0 +1,60 @@
+export function mintRpcId() {
+  const crypto = globalThis.crypto;
+  if (typeof crypto?.randomUUID === "function") return crypto.randomUUID();
+  if (typeof crypto?.getRandomValues === "function") {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    bytes[6] = (bytes[6] & 15) | 64;
+    bytes[8] = (bytes[8] & 63) | 128;
+    const hex = Array.from(bytes, (byte) => 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)}`;
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
+export function rpcPath(method) {
+  return `/api/${method}`;
+}
+
+export const RESPOND_PATH = "/api/respond";
+
+export function wrapClientResponse(rpcId, result) {
+  return {
+    type: "client-response",
+    rpcId,
+    result,
+  };
+}
+
+export function wrapClientRequest(method, payload = {}) {
+  return {
+    type: "client-request",
+    rpcId: mintRpcId(),
+    method,
+    payload,
+  };
+}
+
+export function unwrapServerResponse(body) {
+  if (body === null || typeof body !== "object" || body.type !== "server-response") {
+    return { ok: false, error: { code: "invalid-envelope", message: "invalid rpc envelope" } };
+  }
+  const result = body.result;
+  if (result?.ok === true) return { ok: true, rpcId: body.rpcId, value: result.value };
+  if (result?.ok === false) {
+    return {
+      ok: false,
+      rpcId: body.rpcId,
+      error: result.error ?? { code: "rpc-error", message: "rpc failed" },
+    };
+  }
+  return { ok: false, rpcId: body.rpcId, error: { code: "invalid-envelope", message: "invalid rpc envelope" } };
+}
+
+export function promptPayload(sessionId, text, timeZone) {
+  return {
+    sessionId,
+    mode: "queue",
+    content: [{ type: "text", text: String(text ?? "") }],
+    ...(timeZone ? { clientTimeZone: timeZone } : {}),
+  };
+}

package/larepass/runtime.js

@@ -0,0 +1,395 @@
+import { isAuthFailure } from "./host.js";
+import { listRootSessions, summarizeSession } from "./chat.js";
+import { consumeMuxInbox } from "./mux.js";
+import { wrapClientResponse } from "./rpc.js";
+import { createSessionCache } from "./session-cache.js";
+import { foldTranscript } from "./transcript.js";
+
+const DRAFT_SESSION = "@lares/draft";
+
+function isDraft(sessionId) {
+  return sessionId === DRAFT_SESSION;
+}
+
+function viewOf(state, cache, pendingQuestions) {
+  const page = cache.peek(state.sessionId);
+  const events = page?.events ?? [];
+  const snap = foldTranscript(events);
+  return {
+    sessionId: isDraft(state.sessionId) ? "" : state.sessionId,
+    items: snap.items,
+    messages: snap.messages,
+    running: snap.running,
+    error: state.error || snap.error,
+    failed: state.failed,
+    phase: state.phase,
+    sessions: state.sessions,
+    sessionsReady: state.sessionsReady,
+    historyLoading: Boolean(state.sessionId) && !page?.ready && events.length === 0,
+    question: pendingQuestions.get(state.sessionId) ?? null,
+  };
+}
+
+export function pinnedScroll(top, height, view, slop = 48) {
+  if (height <= view) return { top: 0, stick: true };
+  return { top, stick: height - view - top <= slop };
+}
+
+export function restoreScroll(saved, height, view) {
+  if (!saved || saved.stick) return Math.max(0, height - view);
+  return Math.min(Math.max(0, saved.top), Math.max(0, height - view));
+}
+
+export function createChatRuntime(client) {
+  const listeners = new Set();
+  const cache = createSessionCache();
+  const pendingQuestions = new Map();
+  const state = {
+    sessionId: "",
+    error: "",
+    failed: "",
+    phase: "idle",
+    sessions: [],
+    sessionsReady: false,
+  };
+  let liveScroll = { top: 0, stick: true };
+  let abort = null;
+  let dead = false;
+  let muxLoop = null;
+  let listing = null;
+  let creating = null;
+
+  const emit = () => {
+    const view = viewOf(state, cache, pendingQuestions);
+    for (const listener of listeners) listener(view);
+  };
+
+  function noteFilled(sessionId) {
+    const row = state.sessions.find((item) => item.sessionId === sessionId);
+    if (!row?.blank) return false;
+    row.blank = false;
+    return true;
+  }
+
+  function ingest(sessionId, extra) {
+    const changed = cache.merge(sessionId, extra);
+    const filled = extra?.length ? noteFilled(sessionId) : false;
+    if (filled || (changed && sessionId === state.sessionId)) emit();
+  }
+
+  function rememberListed(row) {
+    if (!row?.sessionId) return;
+    state.sessions = [row, ...state.sessions.filter((item) => item.sessionId !== row.sessionId)];
+    state.sessionsReady = true;
+  }
+
+  function pullHistory(sessionId) {
+    if (!sessionId || dead || isDraft(sessionId)) return Promise.resolve();
+    return cache.load(sessionId, async () => {
+      const history = await client.rpc("session.history", { sessionId });
+      if (dead) return;
+      if (!history.ok) {
+        if (sessionId !== state.sessionId) return;
+        cache.rememberHistory(sessionId, []);
+        state.failed = history.error?.message || history.error?.code || "history";
+        emit();
+        return;
+      }
+      const events = history.value?.events;
+      const changed = cache.rememberHistory(sessionId, events);
+      const filled = events?.length ? noteFilled(sessionId) : false;
+      if (filled || (changed && sessionId === state.sessionId)) emit();
+    });
+  }
+
+  async function listenOnce() {
+    abort?.abort();
+    abort = new AbortController();
+    const opened = await client.openMux(abort.signal);
+    if (isAuthFailure(opened.http)) {
+      state.failed = "unauthorized";
+      emit();
+      return "unauthorized";
+    }
+    if (!opened.ok || !opened.body) {
+      state.failed = opened.error?.message || `mux ${opened.http || opened.status || ""}`;
+      emit();
+      return "error";
+    }
+    state.failed = "";
+    emit();
+    try {
+      for await (const item of consumeMuxInbox(opened.body)) {
+        if (dead) return "stop";
+        if (item.kind === "event") {
+          ingest(item.sessionId, [item.event]);
+          continue;
+        }
+        if (item.kind === "question") {
+          pendingQuestions.set(item.sessionId, {
+            rpcId: item.rpcId,
+            questions: item.questions,
+          });
+          emit();
+          continue;
+        }
+        if (item.kind === "question-resolved") {
+          const current = pendingQuestions.get(item.sessionId);
+          if (!current || !item.rpcId || current.rpcId === item.rpcId) {
+            pendingQuestions.delete(item.sessionId);
+            emit();
+          }
+        }
+      }
+    } catch (err) {
+      if (dead || err?.name === "AbortError") return "stop";
+      state.failed = err instanceof Error ? err.message : String(err);
+      emit();
+      return "error";
+    }
+    return "end";
+  }
+
+  async function listenLoop() {
+    while (!dead && state.sessionId) {
+      const result = await listenOnce();
+      if (result === "unauthorized") {
+        state.phase = "idle";
+        muxLoop = null;
+        return;
+      }
+      if (dead || result === "stop") {
+        if (state.phase === "live") state.phase = "stale";
+        muxLoop = null;
+        return;
+      }
+      await pullHistory(state.sessionId);
+      await new Promise((resolve) => setTimeout(resolve, 800));
+    }
+    muxLoop = null;
+  }
+
+  function ensureMux() {
+    if (dead || muxLoop || !state.sessionId) return;
+    state.phase = "live";
+    muxLoop = listenLoop();
+  }
+
+  async function refreshSessions() {
+    if (dead) return state.sessions;
+    if (listing) return listing;
+    listing = (async () => {
+      const listed = await listRootSessions(client.rpc);
+      if (listed.ok) state.sessions = listed.value.items;
+      state.sessionsReady = true;
+      emit();
+      return state.sessions;
+    })().finally(() => {
+      listing = null;
+    });
+    return listing;
+  }
+
+  function occupy(sessionId) {
+    state.sessionId = sessionId;
+    state.error = "";
+    state.failed = "";
+    liveScroll = cache.scroll(sessionId);
+    emit();
+  }
+
+  function currentIsEmpty() {
+    if (!state.sessionId || isDraft(state.sessionId)) return false;
+    const page = cache.peek(state.sessionId);
+    return Boolean(page?.ready && page.events.length === 0);
+  }
+
+  function reusableBlank() {
+    return state.sessions.find((row) => {
+      if (!row?.blank || !row.sessionId || row.sessionId === state.sessionId) return false;
+      const page = cache.peek(row.sessionId);
+      return !page || page.events.length === 0;
+    })?.sessionId;
+  }
+
+  async function openSession(sessionId) {
+    if (!sessionId || dead || isDraft(sessionId)) return;
+    if (sessionId === state.sessionId) {
+      emit();
+      return;
+    }
+    occupy(sessionId);
+    if (!cache.ready(sessionId)) await pullHistory(sessionId);
+    ensureMux();
+  }
+
+  async function createSession() {
+    if (dead) return;
+    if (creating) return creating;
+    creating = (async () => {
+      if (currentIsEmpty()) {
+        emit();
+        return;
+      }
+      const blankId = reusableBlank();
+      if (blankId) {
+        cache.readyEmpty(blankId);
+        occupy(blankId);
+        ensureMux();
+        pullHistory(blankId);
+        return;
+      }
+      const previous = state.sessionId;
+      cache.readyEmpty(DRAFT_SESSION);
+      occupy(DRAFT_SESSION);
+      ensureMux();
+      const opened = await client.rpc("session.create", {});
+      if (dead) return;
+      if (!opened.ok) {
+        cache.drop(DRAFT_SESSION);
+        if (state.sessionId !== DRAFT_SESSION) return;
+        if (previous) occupy(previous);
+        state.failed = opened.error?.message || opened.error?.code || "session";
+        emit();
+        return;
+      }
+      const sessionId = opened.value.sessionId;
+      cache.readyEmpty(sessionId);
+      rememberListed(summarizeSession({ ...opened.value, sessionId, blank: true }));
+      cache.drop(DRAFT_SESSION);
+      if (state.sessionId !== DRAFT_SESSION && state.sessionId !== sessionId) return;
+      occupy(sessionId);
+      ensureMux();
+    })().finally(() => {
+      creating = null;
+    });
+    return creating;
+  }
+
+  return {
+    snapshot: () => viewOf(state, cache, pendingQuestions),
+    subscribe(listener) {
+      listeners.add(listener);
+      listener(viewOf(state, cache, pendingQuestions));
+      return () => listeners.delete(listener);
+    },
+    async start() {
+      if (dead) return;
+      if (state.phase === "starting") return;
+      if (state.phase === "live" && muxLoop) return;
+      if (state.sessionId && (state.phase === "live" || state.phase === "stale")) {
+        ensureMux();
+        emit();
+        return;
+      }
+      state.phase = "starting";
+      state.failed = "";
+      emit();
+      const probe = await client.probe();
+      if (probe.status !== "ok") {
+        state.phase = "idle";
+        state.failed = probe.status;
+        emit();
+        return;
+      }
+      const opened = await client.ensureSession();
+      if (!opened.ok) {
+        state.phase = "idle";
+        state.failed = opened.error?.message || opened.error?.code || "session";
+        emit();
+        return;
+      }
+      state.sessionId = opened.value.sessionId;
+      liveScroll = cache.scroll(state.sessionId);
+      const listed = Array.isArray(opened.value.sessions)
+        ? (state.sessions = opened.value.sessions, state.sessionsReady = true, Promise.resolve(state.sessions))
+        : refreshSessions();
+      await Promise.all([pullHistory(state.sessionId), listed]);
+      ensureMux();
+      emit();
+    },
+    refreshSessions,
+    async listSessions() {
+      if (state.sessionsReady) {
+        refreshSessions();
+        return state.sessions;
+      }
+      return refreshSessions();
+    },
+    openSession,
+    createSession,
+    async send(text) {
+      if (!state.sessionId || isDraft(state.sessionId)) {
+        return { ok: false, error: { message: "no session" } };
+      }
+      return client.prompt(state.sessionId, text);
+    },
+    async answerQuestion(answers) {
+      const pending = pendingQuestions.get(state.sessionId);
+      if (!pending?.rpcId || typeof client.respond !== "function") {
+        return { ok: false, error: { message: "no question" } };
+      }
+      const receipt = await client.respond(wrapClientResponse(pending.rpcId, {
+        ok: true,
+        value: { sessionId: state.sessionId, answer: { answers } },
+      }));
+      if (!receipt?.accepted) {
+        return { ok: false, error: { message: receipt?.reason || "not-pending" } };
+      }
+      return { ok: true };
+    },
+    preview(path) {
+      if (!state.sessionId || typeof client.preview !== "function") {
+        return Promise.reject(new Error("file_preview_failed"));
+      }
+      return client.preview(state.sessionId, path);
+    },
+    mediaUrl(path, modifiedAt) {
+      return client.mediaUrl?.(state.sessionId, path, modifiedAt) ?? "";
+    },
+    downloadUrl(path) {
+      return client.downloadUrl?.(state.sessionId, path) ?? "";
+    },
+    upload(file, options, sessionId = state.sessionId) {
+      const id = sessionId || state.sessionId;
+      if (!id || isDraft(id) || typeof client.upload !== "function") {
+        return Promise.reject(new Error("file_upload_failed"));
+      }
+      return client.upload(id, file, options);
+    },
+    transcribe(blob, language, signal) {
+      if (typeof client.transcribe !== "function") {
+        return Promise.reject(new Error("voice_failed"));
+      }
+      return client.transcribe(blob, language, signal);
+    },
+    settings: client.settings,
+    rememberScroll(top, height, view) {
+      if (view <= 0) return;
+      liveScroll = pinnedScroll(top, height, view);
+      if (state.sessionId) cache.setScroll(state.sessionId, liveScroll);
+    },
+    pinToBottom() {
+      liveScroll = { top: 0, stick: true };
+      if (state.sessionId) cache.setScroll(state.sessionId, liveScroll);
+    },
+    sticking() {
+      return (state.sessionId ? cache.scroll(state.sessionId) : liveScroll).stick !== false;
+    },
+    scrollTop(height, view) {
+      if (view <= 0) return null;
+      const saved = state.sessionId ? cache.peek(state.sessionId)?.scroll ?? liveScroll : liveScroll;
+      return restoreScroll(saved, height, view);
+    },
+    dispose() {
+      dead = true;
+      abort?.abort();
+      muxLoop = null;
+      listing = null;
+      creating = null;
+      cache.clear();
+      pendingQuestions.clear();
+      listeners.clear();
+    },
+  };
+}