@olares/lares-core 0.15.1 → 0.15.4

package/brand/identity.js

@@ -20,7 +20,9 @@ export function identityPrompt() {
     `You are ${PRODUCT_NAME}, a helpful assistant running on ${PLATFORM_NAME}.`,
     `Prefer olares-cli for ${PLATFORM_NAME} platform tasks when skills apply.`,
     `olares-cli is on PATH; edge login materializes HOME / OLARES_CLI_* for bash when the user opens ${PRODUCT_NAME} via the ${PLATFORM_NAME} entrance.`,
+    "For image, video, audio, or 3D generation and creation, follow the lares-media-create skill.",
     "Use read/write/edit for files; use background jobs for long shell work.",
+    "User-visible files belong in the session workspace (cwd) as relative paths. Do not write them under /app: that is the application overlay, and the chat preview cannot open it.",
     "For the current date or time, run `date`; the process TZ is the user's configured Olares time zone.",
     "Images the user attaches are already in context; read_image is only for image files that exist on disk, never for an attachment.",
     `If asked who you are, answer as ${PRODUCT_NAME} on ${PLATFORM_NAME}.`,
@@ -47,7 +49,9 @@ export function agentsMarkdown() {
 You are helping inside an ${PLATFORM_NAME} workspace via ${PRODUCT_NAME}.
 
 - Prefer olares-cli skills for platform tasks (market, cluster, files, router, …).
+- For image / video / audio / 3D generation, follow the lares-media-create skill.
 - Stay inside the workspace for file edits unless the user explicitly asks otherwise.
+- Write files the user should open as workspace-relative paths (session cwd). \`/app\` is the running application and is not previewable.
 - Prefer structured fs tools (read / write / edit) over shell for file work.
 - Long-running shell work can use background jobs; check results with job_output.
 - \`@path\` in a user message is workspace-relative, not absolute; \`/id\` names a skill.
@@ -59,6 +63,29 @@ You are helping inside an ${PLATFORM_NAME} workspace via ${PRODUCT_NAME}.
 export const LEGACY_AGENTS_SEEDS = [
   `# AGENTS.md
 
+You are helping inside an Olares workspace via Lares.
+
+- Prefer olares-cli skills for platform tasks (market, cluster, files, router, …).
+- For image / video / audio / 3D generation, follow the lares-media-create skill.
+- Stay inside the workspace for file edits unless the user explicitly asks otherwise.
+- Prefer structured fs tools (read / write / edit) over shell for file work.
+- Long-running shell work can use background jobs; check results with job_output.
+- \`@path\` in a user message is workspace-relative, not absolute; \`/id\` names a skill.
+- If asked who you are, you are Lares on Olares.
+`,
+  `# AGENTS.md
+
+You are helping inside an Olares workspace via Lares.
+
+- Prefer olares-cli skills for platform tasks (market, cluster, files, router, …).
+- Stay inside the workspace for file edits unless the user explicitly asks otherwise.
+- Prefer structured fs tools (read / write / edit) over shell for file work.
+- Long-running shell work can use background jobs; check results with job_output.
+- \`@path\` in a user message is workspace-relative, not absolute; \`/id\` names a skill.
+- If asked who you are, you are Lares on Olares.
+`,
+  `# AGENTS.md
+
 You are helping inside an Olares workspace via Dina.
 
 - Prefer olares-cli skills for platform tasks (market, cluster, files, router, …).

package/brand/manifest.js

@@ -1,5 +1,5 @@
 import { PRODUCT_NAME, THEME_COLOR } from "./identity.js";
-import { MARK_PATH } from "../icons/mark.js";
+import { MARK_PATH, MARK_TYPE } from "../icons/mark.js";
 
 export const MANIFEST_PATH = "/lares/manifest.webmanifest";
 
@@ -11,5 +11,5 @@ export const MANIFEST = {
   scope: "/",
   display: "fullscreen",
   theme_color: THEME_COLOR,
-  icons: [{ src: MARK_PATH, sizes: "any", type: "image/svg+xml", purpose: "any" }],
+  icons: [{ src: MARK_PATH, sizes: "any", type: MARK_TYPE, purpose: "any" }],
 };

package/drive/paths.js

@@ -29,6 +29,9 @@ const DATA_NAMES = new Map([
   ["audio/aac", "download.aac"],
   ["audio/flac", "download.flac"],
   ["application/pdf", "download.pdf"],
+  ["model/gltf-binary", "download.glb"],
+  ["model/gltf+json", "download.gltf"],
+  ["model/obj", "download.obj"],
 ]);
 
 function dataUrlFilename(mediaType) {

package/files/preview-groups.js

@@ -1,4 +1,4 @@
-const MEDIA_KINDS = new Set(["image", "video", "audio"]);
+const MEDIA_KINDS = new Set(["image", "video", "audio", "model3d"]);
 
 export function partitionPreviews(paths, previews) {
   const media = [];

package/files/preview.js

@@ -7,6 +7,7 @@ import {
   resolveExistingWorkspacePath,
   resolveWorkspaceRoot,
   workspaceCandidate,
+  workspaceFileAlias,
 } from "../workspace/path.js";
 import { materializeFilesFile } from "./preview-cache.js";
 
@@ -36,6 +37,11 @@ const AUDIO_TYPES = new Map([
   [".aac", "audio/aac"],
   [".flac", "audio/flac"],
 ]);
+const MODEL3D_TYPES = new Map([
+  [".glb", "model/gltf-binary"],
+  [".gltf", "model/gltf+json"],
+  [".obj", "model/obj"],
+]);
 const TEXT_EXTENSIONS = new Set([
   "",
   ".txt", ".log", ".json", ".csv", ".tsv", ".yaml", ".yml", ".toml", ".xml",
@@ -109,6 +115,7 @@ export function previewTypeForName(name) {
   if (IMAGE_TYPES.has(extension)) return { kind: "image", mediaType: IMAGE_TYPES.get(extension) };
   if (VIDEO_TYPES.has(extension)) return { kind: "video", mediaType: VIDEO_TYPES.get(extension) };
   if (AUDIO_TYPES.has(extension)) return { kind: "audio", mediaType: AUDIO_TYPES.get(extension) };
+  if (MODEL3D_TYPES.has(extension)) return { kind: "model3d", mediaType: MODEL3D_TYPES.get(extension) };
   if (extension === ".pdf") return { kind: "pdf", mediaType: "application/pdf" };
   if (extension === ".md" || extension === ".markdown") {
     return { kind: "markdown", mediaType: "text/markdown; charset=utf-8" };
@@ -122,8 +129,24 @@ export async function resolveWorkspaceFile(workspacePath, requestedPath) {
     throw new HttpError("path_invalid", 400, "file path is required");
   }
   const root = await resolveWorkspaceRoot(workspacePath);
-  const candidate = workspaceCandidate(root, requestedPath);
-  const absolutePath = await resolveExistingWorkspacePath(root, candidate);
+  let candidate;
+  try {
+    candidate = workspaceCandidate(root, requestedPath);
+  } catch (error) {
+    const alias = workspaceFileAlias(root, requestedPath);
+    if (!alias || error?.code !== "path_forbidden") throw error;
+    try {
+      candidate = workspaceCandidate(root, alias);
+    } catch {
+      throw error;
+    }
+  }
+  const absolutePath = await resolveExistingWorkspacePath(root, candidate).catch((error) => {
+    if (workspaceFileAlias(root, requestedPath) && error?.code === "file_not_found") {
+      throw new HttpError("path_forbidden", 403, "path leaves the session workspace");
+    }
+    throw error;
+  });
   const info = await stat(absolutePath).catch(() => {
     throw new HttpError("file_not_found", 404, "file was not found");
   });
@@ -284,12 +307,12 @@ async function sendFile(req, res, file, disposition) {
 }
 
 export async function sendRawFile(req, res, file, deps) {
-  if (!["image", "video", "audio", "pdf"].includes(file.kind)) {
+  if (!["image", "video", "audio", "pdf", "model3d"].includes(file.kind)) {
     throw new HttpError("preview_unsupported", 415, "raw preview is not supported for this file");
   }
   // Video and audio are range-streamed, so their total size is not browser
-  // memory pressure. Images and PDFs are consumed as whole documents.
-  if (["image", "pdf"].includes(file.kind) && file.size > MAX_RAW_BYTES) {
+  // memory pressure. Images, PDFs, and 3D meshes are consumed as whole documents.
+  if (["image", "pdf", "model3d"].includes(file.kind) && file.size > MAX_RAW_BYTES) {
     throw new HttpError("file_too_large", 413, `file exceeds ${MAX_RAW_BYTES} bytes`);
   }
   return sendFile(req, res, await ensurePreviewBytes(file, deps), "inline");

package/files/upload-client.js

@@ -7,6 +7,31 @@ function errorCode(payload) {
     : "file_upload_failed";
 }
 
+/**
+ * `fetch` can only authenticate with the Olares cookie, and a host whose page is
+ * cross-origin to the Host — a packaged LarePass desktop build is a `file://`
+ * page — has none, so the upload answers 401 while every RPC call succeeds.
+ * When the host injects a `request` port the upload rides the same auth as the
+ * rest of the client; without one this stays the plain cookie fetch.
+ */
+async function postUpload(options, url, headers, body, signal) {
+  if (typeof options.request === "function") {
+    const res = await options.request(url, { method: "POST", headers, body, signal });
+    return {
+      ok: Boolean(res?.ok),
+      status: Number(res?.status) || 0,
+      // The port already parsed the body; an empty one arrives as undefined.
+      payload: res?.body ?? null,
+    };
+  }
+  const res = await fetch(url, { method: "POST", headers, body, signal });
+  return {
+    ok: res.ok,
+    status: res.status,
+    payload: await res.json().catch(() => null),
+  };
+}
+
 export async function uploadFile(file, sessionId, options = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), UPLOAD_TIMEOUT_MS);
@@ -14,21 +39,21 @@ export async function uploadFile(file, sessionId, options = {}) {
   if (options.signal?.aborted) controller.abort(options.signal.reason);
   else options.signal?.addEventListener("abort", onAbort, { once: true });
   try {
-    const response = await fetch(options.url ?? FILES_UPLOAD_PATH, {
-      method: "POST",
-      headers: {
+    const { ok, status, payload } = await postUpload(
+      options,
+      options.url ?? FILES_UPLOAD_PATH,
+      {
         "content-type": file.type || "application/octet-stream",
         "x-lares-file-name": encodeURIComponent(file.name || "file"),
         "x-lares-session-id": sessionId,
         "x-lares-upload-request-id": options.requestId ?? crypto.randomUUID(),
       },
-      body: file,
-      signal: controller.signal,
-    });
-    const payload = await response.json().catch(() => null);
-    if (!response.ok) {
+      file,
+      controller.signal,
+    );
+    if (!ok) {
       const error = new Error(errorCode(payload));
-      error.status = response.status;
+      error.status = status;
       throw error;
     }
     if (!payload || typeof payload.path !== "string") throw new Error("file_upload_failed");

package/i18n/preview.js

@@ -15,7 +15,8 @@ export const ZH = {
   retry: "重试",
   truncated: "文件较大，仅显示前 1 MB 内容。",
   unsupportedTitle: "暂不支持预览这种文件",
-  unsupported: "目前支持图片、PDF、音视频、Markdown 和文本文件。",
+  unsupported: "目前支持图片、PDF、音视频、3D 模型、Markdown 和文本文件。",
+  model3dHint: "3D 预览在电脑端打开。可先下载此文件。",
   "error.file_not_found": "文件不存在或已被移动",
   "error.file_changed": "文件在打开时发生变化，请重试",
   "error.path_not_file": "这个路径不是文件，无法预览",
@@ -44,7 +45,8 @@ export const EN = {
   retry: "Retry",
   truncated: "This file is large; only the first 1 MB is shown.",
   unsupportedTitle: "This file type cannot be previewed yet",
-  unsupported: "Images, PDF, audio, video, Markdown, and text files are supported.",
+  unsupported: "Images, PDF, audio, video, 3D models, Markdown, and text files are supported.",
+  model3dHint: "3D preview is available on desktop. You can download this file.",
   "error.file_not_found": "The file no longer exists",
   "error.file_changed": "The file changed while it was opening; try again",
   "error.path_not_file": "This path is not a file, so it cannot be previewed",

package/icons/mark.js

@@ -1,21 +1,38 @@
 import { PRODUCT_NAME } from "../brand/identity.js";
 
 /**
- * Product mark: favicon, PWA icon, CSS splash, and slot occupants.
- * An eave over a resident orb — two strokes, readable at 20px collapsed rail.
+ * Product mark: favicon, PWA icon, CSS splash, and slot occupants. Consumers
+ * cache this URL, so the path and the SVG encoding are fixed — publishing the
+ * artwork at a new path leaves stale favicons behind.
+ * Geometry is the design delivery verbatim (ids renamed, aria-label injected).
+ * Keep it a vector — favicon rasterizers drop <image> data URIs.
  */
+export const MARKET_ICON_URL = "https://app.cdn.olares.com/appstore/lares/icon_new.png";
+
 export const MARK_PATH = "/lares/mark.svg";
+export const MARK_TYPE = "image/svg+xml";
 
-export const MARK_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" role="img" aria-label="${PRODUCT_NAME}">
+export const MARK_SVG = `<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256" fill="none" role="img" aria-label="${PRODUCT_NAME}">
   <defs>
-    <linearGradient id="lares-mark" x1="0" y1="0" x2="32" y2="32" gradientUnits="userSpaceOnUse">
-      <stop offset="0" stop-color="#6366F1"/>
-      <stop offset="1" stop-color="#22D3EE"/>
+    <filter id="lares-mark-shadow" x="0" y="0" width="256" height="257.829" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+      <feFlood flood-opacity="0" result="BackgroundImageFix"/>
+      <feBlend mode="normal" in="SourceGraphic" in2="BackgroundImageFix" result="shape"/>
+      <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
+      <feOffset dy="1.82857"/>
+      <feGaussianBlur stdDeviation="0.914286"/>
+      <feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1"/>
+      <feColorMatrix type="matrix" values="0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0.5 0"/>
+      <feBlend mode="normal" in2="shape" result="effect1_innerShadow"/>
+    </filter>
+    <linearGradient id="lares-mark" x1="128" y1="0" x2="128" y2="256" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#FFED52"/>
+      <stop offset="1" stop-color="#EBD304"/>
     </linearGradient>
   </defs>
-  <rect width="32" height="32" rx="8" fill="url(#lares-mark)"/>
-  <path fill="none" stroke="#fff" stroke-width="3.2" stroke-linecap="round" stroke-linejoin="round" d="M6.8 17.4 16 9.2l9.2 8.2"/>
-  <circle cx="16" cy="22" r="3.2" fill="#fff"/>
+  <g filter="url(#lares-mark-shadow)">
+    <rect width="256" height="256" fill="url(#lares-mark)"/>
+    <path fill="#252121" d="M83.5926 125.858C85.7382 144.539 100.433 157.223 120.829 157.998L128.063 158.273H142.829C170.407 158.273 186.978 179.868 179.84 206.507H115.676C86.0222 206.506 68.2049 183.286 75.8798 154.643L83.5926 125.858ZM104.576 47.5429C133.193 47.5429 150.386 69.9505 142.98 97.5918L128.319 152.309C99.7025 152.309 82.5086 129.9 89.915 102.259L100.338 63.3618C102.534 55.1648 97.833 48.3464 89.5437 47.7079L87.3945 47.5429H104.576Z"/>
+  </g>
 </svg>`;
 
 /** Inline form for CSS `background-image`, which cannot reference a route that may 404 mid-boot. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olares/lares-core",
-  "version": "0.15.1",
+  "version": "0.15.4",
   "description": "Lares 共享业务核心：Router、workspace、文件/媒体、Olares 身份（无 UI、无平台壳）",
   "type": "module",
   "repository": {
@@ -44,6 +44,10 @@
     "./i18n/preview": "./i18n/preview.js",
     "./i18n/mobile": "./i18n/mobile.js",
     "./router/catalog": "./router/catalog.js",
+    "./router/catalog-cache": {
+      "types": "./router/catalog-cache.d.ts",
+      "default": "./router/catalog-cache.js"
+    },
     "./router/gateway": "./router/gateway.js",
     "./router/models": {
       "types": "./router/models.d.ts",

package/router/catalog-cache.d.ts

@@ -0,0 +1,29 @@
+import type { RouterCatalogRow } from "./catalog.js";
+
+export const DEFAULT_TTL_MS: number;
+
+export function catalogSeedPath(dataDir?: string): string | null;
+export function writeCatalogSeed(payload: unknown, dataDir?: string): void;
+
+export interface CatalogSnapshot {
+  payload: unknown;
+  rows: RouterCatalogRow[];
+  fetchedAt: number;
+}
+
+export class CatalogCache {
+  constructor(options?: {
+    ttlMs?: number;
+    fetch?: typeof fetch;
+    now?: () => number;
+    dataDir?: string;
+  });
+  reset(): void;
+  invalidate(): void;
+  seed(payload: unknown): void;
+  snapshot(): CatalogSnapshot;
+  restore(snap: CatalogSnapshot | { payload: unknown; rows?: RouterCatalogRow[]; fetchedAt?: number } | null): void;
+  get(): Promise<CatalogSnapshot>;
+}
+
+export const catalogCache: CatalogCache;

package/router/catalog-cache.js

@@ -0,0 +1,144 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { routerCatalogRows } from "./catalog.js";
+import { routerGatewayUrl, routerHeaders } from "./gateway.js";
+
+export const DEFAULT_TTL_MS = 15_000;
+
+export function catalogSeedPath(dataDir = process.env.LARES_DATA_DIR?.trim()) {
+  return dataDir ? join(dataDir, "router-catalog.json") : null;
+}
+
+export function writeCatalogSeed(payload, dataDir) {
+  const path = catalogSeedPath(dataDir);
+  if (!path || payload == null || typeof payload !== "object") return;
+  writeFileSync(path, JSON.stringify(payload), { mode: 0o600 });
+}
+
+function readCatalogSeed(dataDir) {
+  const path = catalogSeedPath(dataDir);
+  if (!path) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (parsed && typeof parsed === "object") return parsed;
+  } catch {
+    // Missing or unreadable seed is a cold start, not a failure.
+  }
+  return null;
+}
+
+/**
+ * In-process Router /models cache. TTL plus coalesced upstream fetches; a
+ * seed file lets the dsh child reuse the boot process's catalog read.
+ */
+export class CatalogCache {
+  /**
+   * @param {{
+   *   ttlMs?: number,
+   *   fetch?: typeof fetch,
+   *   now?: () => number,
+   *   dataDir?: string,
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.ttlMs = options.ttlMs && options.ttlMs > 0 ? options.ttlMs : DEFAULT_TTL_MS;
+    this.fetchImpl = options.fetch ?? ((url, init) => globalThis.fetch(url, init));
+    this.now = options.now ?? Date.now;
+    this.dataDir = options.dataDir;
+    this.reset();
+  }
+
+  reset() {
+    this.payload = null;
+    this.rows = [];
+    this.fetchedAt = 0;
+    this.inflight = null;
+    this.primed = false;
+  }
+
+  invalidate() {
+    this.fetchedAt = 0;
+  }
+
+  /**
+   * @param {unknown} payload
+   */
+  seed(payload) {
+    this.primed = true;
+    this.accept(payload);
+    writeCatalogSeed(payload, this.dataDir);
+  }
+
+  snapshot() {
+    return { payload: this.payload, rows: this.rows, fetchedAt: this.fetchedAt };
+  }
+
+  /**
+   * Revert to a prior snapshot after a later consumer (settings, default
+   * selection) failed so search / STT / chat keep one catalog.
+   * @param {{ payload: unknown, rows?: unknown[], fetchedAt?: number } | null} snap
+   */
+  restore(snap) {
+    if (snap?.payload == null) {
+      this.payload = null;
+      this.rows = [];
+      this.fetchedAt = 0;
+      return;
+    }
+    this.payload = snap.payload;
+    this.rows = Array.isArray(snap.rows) ? snap.rows : routerCatalogRows(snap.payload);
+    this.fetchedAt = Number.isFinite(snap.fetchedAt) ? snap.fetchedAt : 0;
+    this.primed = true;
+    writeCatalogSeed(snap.payload, this.dataDir);
+  }
+
+  async get() {
+    if (this.payload && this.fetchedAt !== 0 && this.now() - this.fetchedAt < this.ttlMs) {
+      return this.snapshot();
+    }
+    if (this.inflight) return this.inflight;
+    const pending = this.load();
+    const shared = pending.finally(() => {
+      if (this.inflight === shared) this.inflight = null;
+    });
+    this.inflight = shared;
+    return shared;
+  }
+
+  async load() {
+    if (!this.primed) {
+      this.primed = true;
+      const seeded = readCatalogSeed(this.dataDir);
+      if (seeded) {
+        this.accept(seeded);
+        return this.snapshot();
+      }
+    }
+    const response = await this.fetchImpl(`${routerGatewayUrl()}/models?include_not_ready=true`, {
+      method: "GET",
+      headers: routerHeaders(),
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!response.ok) {
+      throw Object.assign(new Error(`Router /models returned ${response.status}`), {
+        code: "router_unavailable",
+        status: 503,
+      });
+    }
+    const payload = await response.json();
+    this.accept(payload);
+    writeCatalogSeed(payload, this.dataDir);
+    return this.snapshot();
+  }
+
+  /**
+   * @param {unknown} payload
+   */
+  accept(payload) {
+    this.payload = payload;
+    this.rows = routerCatalogRows(payload);
+    this.fetchedAt = this.now();
+  }
+}
+
+export const catalogCache = new CatalogCache();

package/router/catalog-sync.js

@@ -1,20 +1,41 @@
 import { createInFlightCoalescer } from "../tools/async.js";
+import { catalogCache } from "./catalog-cache.js";
 import {
   LLM_SETTINGS_NS,
   ROUTER_PROVIDER_ID,
   catalogSettingsOps,
+  chatModelsFromRouterCatalog,
   defaultNeedsRepair,
-  fetchChatModels,
   listedCatalog,
   parseDefaultModelRequest,
   pickDefaultModel,
   unregisteredRouterFailure,
 } from "./models.js";
+import { forgetSttModel } from "./stt.js";
 
 function messageOf(err) {
   return err instanceof Error ? err.message : String(err);
 }
 
+let adapterRevision = 0;
+/** @type {Set<(revision: number) => void>} */
+const revisionListeners = new Set();
+
+export function catalogRevision() {
+  return adapterRevision;
+}
+
+/** @param {(revision: number) => void} listener */
+export function onCatalogRevision(listener) {
+  revisionListeners.add(listener);
+  return () => revisionListeners.delete(listener);
+}
+
+function bumpRevision() {
+  adapterRevision += 1;
+  for (const listener of revisionListeners) listener(adapterRevision);
+}
+
 /**
  * @param {{
  *   mutateSettings: (ns: string, ops: unknown[]) => Promise<void>,
@@ -23,13 +44,23 @@ function messageOf(err) {
  * }} ports
  */
 async function performRefresh(ports) {
-  const models = await fetchChatModels();
-  await ports.mutateSettings(LLM_SETTINGS_NS, catalogSettingsOps(models));
-  const current = ports.currentSelection();
-  if (defaultNeedsRepair(current, models)) {
-    await ports.saveSelection({ provider: ROUTER_PROVIDER_ID, model: pickDefaultModel(models).id });
+  const previous = catalogCache.snapshot();
+  catalogCache.invalidate();
+  try {
+    const { payload } = await catalogCache.get();
+    const models = chatModelsFromRouterCatalog(payload);
+    await ports.mutateSettings(LLM_SETTINGS_NS, catalogSettingsOps(models));
+    const current = ports.currentSelection();
+    if (defaultNeedsRepair(current, models)) {
+      await ports.saveSelection({ provider: ROUTER_PROVIDER_ID, model: pickDefaultModel(models).id });
+    }
+    forgetSttModel();
+    bumpRevision();
+    return models;
+  } catch (err) {
+    catalogCache.restore(previous);
+    throw err;
   }
-  return models;
 }
 
 const coalesceRefresh = createInFlightCoalescer();
@@ -83,5 +114,10 @@ export async function saveDefault(ports, request) {
 }
 
 export function catalogState(ports, listed) {
-  return { default: currentDefault(ports), models: listed.models, failures: listed.failures };
+  return {
+    default: currentDefault(ports),
+    models: listed.models,
+    failures: listed.failures,
+    revision: catalogRevision(),
+  };
 }

package/router/models.d.ts

@@ -13,4 +13,5 @@ export function fetchRouterModels(env: {
   routerUrl?: string | null;
   routerApiKey?: string | null;
   olaresAppId?: string | null;
+  dataDir?: string | null;
 }): Promise<RouterModelEntry[]>;

package/router/models.js

@@ -1,3 +1,4 @@
+import { writeCatalogSeed } from "./catalog-cache.js";
 import { routerCatalogRows } from "./catalog.js";
 import { routerAuthHeaders, routerGatewayUrl, routerShimBaseUrl } from "./gateway.js";
 
@@ -72,7 +73,7 @@ export async function fetchChatModels() {
  */
 export async function fetchRouterModels(env) {
   const routerUrl = String(env.routerUrl ?? "").replace(/\/+$/, "") || routerGatewayUrl();
-  const res = await fetch(`${routerUrl}/models`, {
+  const res = await fetch(`${routerUrl}/models?include_not_ready=true`, {
     method: "GET",
     headers: {
       ...routerAuthHeaders(env.routerApiKey, env.olaresAppId),
@@ -81,7 +82,9 @@ export async function fetchRouterModels(env) {
     signal: AbortSignal.timeout(15_000),
   });
   if (!res.ok) throw new Error(`Router /models returned ${res.status}`);
-  return modelsFromRouterCatalog(await res.json());
+  const payload = await res.json();
+  writeCatalogSeed(payload, env.dataDir);
+  return modelsFromRouterCatalog(payload);
 }
 
 export function parseDefaultModelRequest(request) {

package/router/search.js

@@ -1,3 +1,4 @@
+import { catalogCache } from "./catalog-cache.js";
 import { routerCatalogRows } from "./catalog.js";
 import { routerGatewayUrl, routerHeaders } from "./gateway.js";
 
@@ -57,18 +58,8 @@ export function searchSourcesFromRouter(payload) {
 const DEFAULT_TIMEOUT_MS = 20_000;
 
 export async function fetchRouterSearchModels() {
-  const response = await fetch(`${routerGatewayUrl()}/models`, {
-    method: "GET",
-    headers: routerHeaders(),
-    signal: AbortSignal.timeout(15_000),
-  });
-  if (!response.ok) {
-    throw Object.assign(new Error(`Router /models returned ${response.status}`), {
-      code: "router_unavailable",
-      status: 503,
-    });
-  }
-  return searchModelsFromRouterCatalog(await response.json());
+  const { payload } = await catalogCache.get();
+  return searchModelsFromRouterCatalog(payload);
 }
 
 /**

package/router/shim.js

@@ -1,6 +1,7 @@
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
-import { readBody, sendError } from "../tools/http.js";
+import { readBody, sendError, sendJson } from "../tools/http.js";
+import { catalogCache } from "./catalog-cache.js";
 import { carriesWebpImage, transcodeWebpImages } from "../media/router-images.js";
 import { routerAuthHeaders, routerGatewayUrl } from "./gateway.js";
 import { STT_MAX_AUDIO_BYTES } from "./stt.js";
@@ -42,7 +43,9 @@ export function shimBudget(suffix) {
   };
 }
 
+/** @returns {Record<string, string>} */
 export function shimRequestHeaders(incoming, env = process.env) {
+  /** @type {Record<string, string>} */
   const headers = {};
   for (const [key, value] of Object.entries(incoming)) {
     if (value == null || DROPPED_REQ.has(key.toLowerCase())) continue;
@@ -75,7 +78,72 @@ export function healthPayload(env = process.env) {
   };
 }
 
+function isModelsGet(req) {
+  const method = (req.method ?? "GET").toUpperCase();
+  if (method !== "GET" && method !== "HEAD") return false;
+  const u = new URL(req.url ?? "/", "http://x");
+  return llmShimSuffix(u.pathname).replace(/\/+$/, "") === "models";
+}
+
+function serveCachedModels(req, res) {
+  void catalogCache.get().then(
+    ({ payload }) => {
+      if (res.headersSent) {
+        res.destroy();
+        return;
+      }
+      if ((req.method ?? "GET").toUpperCase() === "HEAD") {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end();
+        return;
+      }
+      sendJson(res, 200, payload);
+    },
+    (err) => {
+      if (res.headersSent) {
+        res.destroy();
+        return;
+      }
+      sendError(res, err, "llm_proxy_failed");
+    },
+  );
+}
+
+function downstreamCancellation(req, res) {
+  const controller = new AbortController();
+  let finished = false;
+
+  const cleanup = () => {
+    req.off("aborted", cancel);
+    res.off("finish", finish);
+    res.off("close", close);
+  };
+  const cancel = () => {
+    if (!controller.signal.aborted) {
+      controller.abort(new Error("LLM downstream disconnected"));
+    }
+    cleanup();
+  };
+  const finish = () => {
+    finished = true;
+    cleanup();
+  };
+  const close = () => {
+    if (!finished) cancel();
+    else cleanup();
+  };
+
+  req.once("aborted", cancel);
+  res.once("finish", finish);
+  res.once("close", close);
+  return controller;
+}
+
 export function proxyToRouter(req, res, env = process.env) {
+  if (isModelsGet(req)) {
+    serveCachedModels(req, res);
+    return;
+  }
   const routerUrl = routerGatewayUrl(env);
   const rawUrl = req.url ?? "/";
   const u = new URL(rawUrl, "http://x");
@@ -85,6 +153,7 @@ export function proxyToRouter(req, res, env = process.env) {
   const headers = shimRequestHeaders(req.headers, env);
   const transport = target.protocol === "https:" ? httpsRequest : httpRequest;
   const method = (req.method ?? "GET").toUpperCase();
+  const cancellation = downstreamCancellation(req, res);
 
   const run = async () => {
     let body;
@@ -96,16 +165,22 @@ export function proxyToRouter(req, res, env = process.env) {
       if (!budget.audio && carriesWebpImage(body)) body = await transcodeWebpImages(body);
       headers["content-length"] = String(body.length);
     }
+    if (cancellation.signal.aborted) return;
 
     const upstream = transport(
       target,
-      { method, headers, timeout: budget.timeoutMs },
+      { method, headers, timeout: budget.timeoutMs, signal: cancellation.signal },
       (up) => {
+        if (cancellation.signal.aborted) {
+          up.destroy();
+          return;
+        }
         res.writeHead(up.statusCode ?? 502, shimResponseHeaders(up.headers));
         up.pipe(res);
       },
     );
     upstream.on("error", (err) => {
+      if (cancellation.signal.aborted) return;
       if (res.headersSent) {
         res.destroy();
         return;
@@ -125,6 +200,7 @@ export function proxyToRouter(req, res, env = process.env) {
   };
 
   void run().catch((err) => {
+    if (cancellation.signal.aborted) return;
     if (res.headersSent) {
       res.destroy();
       return;

package/router/stt.js

@@ -1,6 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { createInFlightCoalescer } from "../tools/async.js";
-import { routerCatalogRows } from "./catalog.js";
+import { catalogCache } from "./catalog-cache.js";
 import { routerShimBaseUrl } from "./gateway.js";
 
 const STT_HINTS = /whisper|\bstt\b|\basr\b|transcri/i;
@@ -67,30 +66,23 @@ export function audioFilenameForContentType(contentType) {
 }
 
 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);
+  try {
+    if (options?.refresh) catalogCache.invalidate();
+    const { rows } = await catalogCache.get();
+    return rows.map(({ id, mode }) => ({ id, mode }));
+  } catch (err) {
+    const status = err && typeof err === "object" && "status" in err ? Number(err.status) : 503;
+    throw new VoiceError(
+      "voice_model_unavailable",
+      status || 503,
+      err instanceof Error ? err.message : String(err),
+    );
+  }
 }
 
 /** @returns {Promise<string[]>} */
@@ -119,7 +111,6 @@ export async function resolveSttModel(preferred, options) {
 
 export function forgetSttModel() {
   resolved = null;
-  catalog = null;
 }
 
 /** @param {Record<string, string>} fields @param {{ filename: string, contentType: string, bytes: Buffer }} file */

package/voice/client.js

@@ -62,23 +62,39 @@ export function mergeTranscript(draft, transcript) {
   return `${base} ${text}`;
 }
 
+function transcribeErrorCode(payload) {
+  const code = payload && typeof payload === "object" ? payload.error?.code : undefined;
+  return typeof code === "string" ? code : "voice_failed";
+}
+
+/**
+ * The only voice call that carries a body, and so the only one that cannot go
+ * through `createHostSettings`. Like the upload it must accept the host's
+ * `request` port: a cross-origin host page sends no Olares cookie, so a plain
+ * `fetch` here answers 401 even though `/config`, `/status` and `/models` — which
+ * do ride the port — all succeed.
+ */
 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,
-  });
+  const url = `${base}/transcribe${query}`;
+  const headers = { "content-type": blob.type || "audio/webm" };
+
+  if (typeof options.request === "function") {
+    const res = await options.request(url, { method: "POST", headers, body: blob, signal });
+    if (!res?.ok) throw new Error(transcribeErrorCode(res?.body));
+    return String(res?.body?.text ?? "").trim();
+  }
+
+  const res = await fetch(url, { method: "POST", headers, body: blob, signal });
   if (!res.ok) {
-    let code = "voice_failed";
+    let payload = null;
     try {
-      code = (await res.json())?.error?.code ?? code;
+      payload = await res.json();
     } catch {
-      /* keep default */
+      /* fall back to the generic code */
     }
-    throw new Error(code);
+    throw new Error(transcribeErrorCode(payload));
   }
   return String((await res.json())?.text ?? "").trim();
 }

package/workspace/path.js

@@ -1,6 +1,6 @@
 import { lstatSync } from "node:fs";
 import { mkdir, realpath, stat } from "node:fs/promises";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { HttpError } from "../tools/http.js";
 
 export function isInsideWorkspace(root, target) {
@@ -14,6 +14,21 @@ export async function resolveWorkspaceRoot(workspacePath) {
   });
 }
 
+/**
+ * Preview only serves the session workspace. Agents sometimes write
+ * `/app/name.ext` (the application overlay) while the open chip still points
+ * there; alias that basename into the workspace. Nested overlay paths
+ * (`/app/packages/x`) and any other filesystem root (`/tmp/x`) stay forbidden.
+ */
+export function workspaceFileAlias(root, requestedPath) {
+  if (typeof requestedPath !== "string" || !isAbsolute(requestedPath)) return null;
+  if (isInsideWorkspace(root, requestedPath)) return null;
+  if (dirname(requestedPath) !== "/app") return null;
+  const base = basename(requestedPath);
+  if (!base || base === "." || base === "..") return null;
+  return base;
+}
+
 export function workspaceCandidate(root, requestedPath) {
   const candidate = resolve(root, requestedPath);
   if (!isInsideWorkspace(root, candidate)) {