@olares/lares-core 0.15.1 → 0.15.2

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olares/lares-core",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "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";
@@ -75,7 +76,42 @@ 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");
+    },
+  );
+}
+
 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");

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/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)) {