@olares/lares-core 0.15.0

package/README.md

@@ -0,0 +1,23 @@
+# @olares/lares-core
+
+Business rules live here once. `packages/web` and `packages/mobile` only render
+and bind UI; they must not grow a second copy of catalog, path, media, or
+identity policy.
+
+Import surfaces (`@olares/lares-core/<export>`):
+
+- `tools/*`: HTTP helpers, JSON file IO, in-flight coalescing, insecure-origin `randomUUID` shim.
+- `router/*`: Router transport contracts, catalog normalization, LLM shim, model / STT / search policy, catalog sync, session model switching, and search error codes.
+- `workspace/*`: workspace boundaries, default seed, and dsh session-to-workspace resolution.
+- `files/*`: intake, preview workspace, markdown rewrite, Host upload/preview HTTP.
+- `drive/*`: path policy, tool execution, present cards, and agent tool definitions.
+- `voice/*`, `search/*`: STT/search settings, Host payloads, and client API contracts.
+- `olares/*`: Olares entrance identity, trusted-host loopback, and CLI session materialization.
+- `larepass/host`: find the Lares entrance from LarePass `myApps`, PC-test proxy URLs, Host probe, and `hostConfigFromEnv`.
+- `larepass/rpc`, `larepass/transcript`, `larepass/context-provenance`, `larepass/tool-row`, `larepass/stage-copy`, `larepass/chat`, `larepass/mux`, `larepass/session-cache`, `larepass/runtime`, `larepass/settings`: dsh host-RPC envelope, session timeline fold (user / context / reasoning / tool / retry / files; same classification as dsh conversation nodes), English stage chrome copy and tool-row variants, browser mux as WebSocket (same frames as PC), per-session page cache (switch reads cache; history/mux write only on change), the LarePass chat runtime (UI only subscribes), and Host HTTP for model / voice / search settings.
+- `brand/identity`, `brand/manifest`: product identity and PWA manifest consumed by the Host and clients.
+- `icons/*`: product mark SVG and public icon paths (no React).
+- `i18n/*`: ZH/EN catalogs and `t` / `{name}` interpolation (no React, no dsh locale), including the LarePass mobile shell.
+
+Core may depend on Node.js and backend libraries, but never on `packages/web`,
+`packages/mobile`, React, or browser UI.

package/brand/identity.d.ts

@@ -0,0 +1,9 @@
+export const PRODUCT_NAME: string;
+export const PLATFORM_NAME: string;
+export const UPSTREAM_TITLE: string;
+export const THEME_COLOR: string;
+export function replaceProductTitle(title: string): string;
+export function identityPrompt(): string;
+export function surfacePrompt(webUrl: string): string;
+export function agentsMarkdown(): string;
+export const LEGACY_AGENTS_SEEDS: readonly string[];

package/brand/identity.js

@@ -0,0 +1,82 @@
+/**
+ * Product identity. Wordmark, LLM persona, AGENTS.md, and the web-surface
+ * prompt all read from here — change this file, not the call sites.
+ */
+
+export const PRODUCT_NAME = "Lares";
+export const PLATFORM_NAME = "Olares";
+/** dsh document.title needle. Client rewrites it; never ship this as our copy. */
+export const UPSTREAM_TITLE = "DeepSeek Harness";
+
+export const THEME_COLOR = "#6366F1";
+
+export function replaceProductTitle(title) {
+  return String(title ?? "").split(UPSTREAM_TITLE).join(PRODUCT_NAME);
+}
+
+/** Model-facing identity. Affirm the product; do not name the upstream kernel. */
+export function identityPrompt() {
+  return [
+    `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.`,
+    "Use read/write/edit for files; use background jobs for long shell work.",
+    "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}.`,
+  ].join(" ");
+}
+
+/**
+ * Browser-surface orientation. The Host owns this paragraph; keep internals
+ * (HMR / checkout) out of the model prompt.
+ * @param {string} webUrl
+ */
+export function surfacePrompt(webUrl) {
+  return [
+    `You are interacting with the user through ${PRODUCT_NAME} at ${webUrl}.`,
+    `When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean ${PRODUCT_NAME}.`,
+    "The browser provides no implicit DOM, route, or screenshot context.",
+    `If asked who you are, answer as ${PRODUCT_NAME} on ${PLATFORM_NAME}.`,
+  ].join(" ");
+}
+
+export function agentsMarkdown() {
+  return `# AGENTS.md
+
+You are helping inside an ${PLATFORM_NAME} workspace via ${PRODUCT_NAME}.
+
+- 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 ${PRODUCT_NAME} on ${PLATFORM_NAME}.
+`;
+}
+
+/** Previous seeded AGENTS.md texts. Rewrite in place so old workspaces pick up the brand. */
+export const LEGACY_AGENTS_SEEDS = [
+  `# AGENTS.md
+
+You are helping inside an Olares workspace via Dina.
+
+- 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 Dina on Olares, not DeepSeek Harness.
+`,
+  `# 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, not DeepSeek Harness.
+`,
+];

package/brand/manifest.js

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

package/drive/download.js

@@ -0,0 +1,40 @@
+import { spawn } from "node:child_process";
+
+/** Enough of a CLI failure to act on, without pulling a progress log into the turn. */
+const STDERR_LIMIT = 2000;
+
+/**
+ * Stream one files-backend file onto local disk.
+ *
+ * The edge identity is already materialized into `process.env` (HOME /
+ * OLARES_CLI_*) by `lares-olares-identity`, which is what the bash tool relies
+ * on too, so the child inherits it rather than resolving a profile of its own.
+ * @param spawnFn - seam for tests; the real spawn otherwise.
+ */
+export function runOlaresDownload(source, absolutePath, options = {}) {
+  const { signal, overwrite = false, resume = false, spawnFn = spawn } = options;
+  return new Promise((resolve, reject) => {
+    const args = ["files", "download", source, absolutePath];
+    if (overwrite) args.push("--overwrite");
+    else if (resume) args.push("--resume");
+    const child = spawnFn("olares-cli", args, {
+      env: process.env,
+      stdio: ["ignore", "ignore", "pipe"],
+      ...(signal ? { signal } : {}),
+    });
+    let stderr = "";
+    child.stderr?.on("data", (chunk) => {
+      stderr = `${stderr}${chunk}`.slice(-STDERR_LIMIT);
+    });
+    child.on("error", (error) => {
+      reject(new Error(`olares-cli files download failed: ${error.message}`));
+    });
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`olares-cli files download exited ${code}: ${stderr.trim() || "no output"}`));
+    });
+  });
+}

package/drive/execute.js

@@ -0,0 +1,143 @@
+import { statSync } from "node:fs";
+import { encodeWorkspaceVideo } from "../media/ffmpeg-run.js";
+import { workspaceRootFromSession } from "../workspace/env.js";
+import {
+  prepareWorkspaceTarget,
+  resolveExistingWorkspacePath,
+  resolveWorkspaceRoot,
+  workspaceCandidate,
+} from "../workspace/path.js";
+import { runOlaresDownload } from "./download.js";
+import { statFilesFile } from "./ls.js";
+import {
+  describeFetch,
+  describeFfmpegEncode,
+  describeUrlFetch,
+  describeWorkspacePublish,
+  resolveFetch,
+  resolveFfmpegEncode,
+  resolveUrlFetch,
+  resolveWorkspacePublish,
+} from "./paths.js";
+import { downloadUrl, saveDataUrl } from "./url-download.js";
+
+export async function executeDriveFetch(args, exec, download) {
+  const run = download ?? runOlaresDownload;
+  const { source, destination } = resolveFetch(args);
+  const root = workspaceRootFromSession(exec);
+  const absolutePath = await prepareWorkspaceTarget(root, destination, args.overwrite === true);
+  await run(source, absolutePath, {
+    signal: exec.signal,
+    overwrite: args.overwrite === true,
+  });
+  return { path: destination, bytes: statSync(absolutePath).size };
+}
+
+export async function executeUrlFetch(args, exec, download) {
+  const run = download ?? downloadUrl;
+  const resolved = resolveUrlFetch(args);
+  const root = workspaceRootFromSession(exec);
+  const absolutePath = await prepareWorkspaceTarget(root, resolved.destination, args.overwrite === true);
+  const result = resolved.kind === "data"
+    ? await saveDataUrl(String(args.url), absolutePath, { overwrite: args.overwrite === true })
+    : await run(resolved.source, absolutePath, {
+      signal: exec.signal,
+      overwrite: args.overwrite === true,
+    });
+  return { path: resolved.destination, bytes: result.bytes, mediaType: result.mediaType };
+}
+
+export async function executeWorkspacePublish(args, exec, statFile) {
+  const resolved = resolveWorkspacePublish(args);
+  if (resolved.origin === "files") {
+    const info = await (statFile ?? statFilesFile)(resolved.path, { signal: exec.signal });
+    return { path: resolved.path, bytes: info.size };
+  }
+  const root = await resolveWorkspaceRoot(workspaceRootFromSession(exec));
+  const absolutePath = await resolveExistingWorkspacePath(
+    root,
+    workspaceCandidate(root, resolved.path),
+  );
+  const info = statSync(absolutePath);
+  if (!info.isFile()) throw new Error(`${resolved.path} is not a regular file`);
+  return { path: resolved.path, bytes: info.size };
+}
+
+export async function executeFfmpegEncode(args, exec, encode) {
+  const run = encode ?? encodeWorkspaceVideo;
+  const resolved = resolveFfmpegEncode(args);
+  const root = workspaceRootFromSession(exec);
+  const absolutePath = await prepareWorkspaceTarget(root, resolved.destination, resolved.overwrite);
+  let inputAbsolute = null;
+  let subtitlesAbsolute = null;
+  if (resolved.input) {
+    const workspace = await resolveWorkspaceRoot(root);
+    inputAbsolute = await resolveExistingWorkspacePath(
+      workspace,
+      workspaceCandidate(workspace, resolved.input),
+    );
+    if (resolved.subtitles) {
+      subtitlesAbsolute = await resolveExistingWorkspacePath(
+        workspace,
+        workspaceCandidate(workspace, resolved.subtitles),
+      );
+    }
+  }
+  const result = await run({
+    ...resolved,
+    absolutePath,
+    inputAbsolute,
+    subtitlesAbsolute,
+  }, { signal: exec.signal });
+  return {
+    path: resolved.destination,
+    bytes: result.bytes,
+    encoder: result.encoder,
+    speed: result.speed,
+  };
+}
+
+export function producedEditCard(title, path) {
+  return {
+    card: "generic",
+    kind: "edit",
+    title,
+    ...(path ? { locations: [{ path }] } : {}),
+  };
+}
+
+export function presentDriveFetch(args) {
+  const fetched = describeFetch(args);
+  return producedEditCard(
+    `Fetch ${fetched?.source ?? String(args.path ?? "")}`,
+    fetched?.destination,
+  );
+}
+
+export function presentUrlFetch(args) {
+  const fetched = describeUrlFetch(args);
+  return producedEditCard(
+    fetched?.kind === "data"
+      ? `Save ${fetched.destination}`
+      : `Download ${fetched?.source ?? String(args.url ?? "").slice(0, 160)}`,
+    fetched?.destination,
+  );
+}
+
+export function presentWorkspacePublish(args) {
+  const published = describeWorkspacePublish(args);
+  return producedEditCard(
+    `Publish ${published?.path ?? String(args.path ?? "").slice(0, 160)}`,
+    published?.path,
+  );
+}
+
+export function presentFfmpegEncode(args) {
+  const encoded = describeFfmpegEncode(args);
+  return producedEditCard(
+    encoded?.pattern
+      ? `Encode ${encoded.pattern} → ${encoded.destination}`
+      : `Encode ${encoded?.destination ?? String(args.destination ?? "").slice(0, 160)}`,
+    encoded?.destination,
+  );
+}

package/drive/files-path.js

@@ -0,0 +1,55 @@
+/** Namespaces `olares-cli files download` serves. */
+const DOWNLOADABLE = new Set([
+  "drive", "cache", "sync", "external", "awss3", "google", "dropbox", "tencent",
+]);
+
+/**
+ * Files UI and knowledge sometimes omit `drive/` or prefix a slash on a real
+ * files address. Only those shapes unwrap; a POSIX path stays rejected.
+ */
+function canonicalizeFilesAddress(value) {
+  let source = String(value ?? "").trim();
+  if (source.startsWith("/")) {
+    const rest = source.slice(1);
+    const first = rest.split("/", 1)[0];
+    if (first === "Home" || DOWNLOADABLE.has(first)) source = rest;
+  }
+  if (source === "Home" || source.startsWith("Home/")) source = `drive/${source}`;
+  return source;
+}
+
+/**
+ * @returns a validated `<fileType>/<extend>/<subPath>` files-backend address.
+ * @throws when the value is empty, a URL, a directory, or outside downloadable namespaces.
+ */
+export function parseFilesPath(value) {
+  const source = canonicalizeFilesAddress(value);
+  if (source === "" || source.includes("\0")) {
+    throw new Error("path is required, e.g. drive/Home/Documents/clip.webm");
+  }
+  if (source.startsWith("/") || /^[a-z]+:/i.test(source)) {
+    throw new Error(`"${source}" is not an Olares files path; expected <fileType>/<extend>/<subPath>`);
+  }
+  if (source.endsWith("/")) {
+    throw new Error(`"${source}" names a directory; expected a single file`);
+  }
+  const segments = source.split("/");
+  if (!DOWNLOADABLE.has(segments[0])) {
+    throw new Error(
+      `"${segments[0]}" is not a downloadable namespace; expected one of ${[...DOWNLOADABLE].join(", ")}`,
+    );
+  }
+  if (segments.length < 3 || segments.some((part) => part === "" || part === "." || part === "..")) {
+    throw new Error(`"${source}" is malformed; expected <fileType>/<extend>/<subPath>`);
+  }
+  return source;
+}
+
+export function isFilesPath(value) {
+  try {
+    parseFilesPath(value);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/drive/ls.js

@@ -0,0 +1,126 @@
+import { spawn } from "node:child_process";
+import { parseFilesPath } from "./files-path.js";
+
+const STDERR_LIMIT = 2000;
+const STDOUT_LIMIT = 8 * 1024 * 1024;
+
+function lookupError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+/**
+ * Children of one `olares-cli files ls --json` envelope.
+ * Drive-like namespaces use `items`; cloud namespaces use `data`.
+ */
+export function filesLsChildren(envelope) {
+  if (envelope == null || typeof envelope !== "object") return [];
+  const body = envelope.data !== undefined && !Array.isArray(envelope.items)
+    ? envelope.data
+    : envelope;
+  if (Array.isArray(body)) return body;
+  if (body && typeof body === "object") {
+    if (Array.isArray(body.items)) return body.items;
+    if (Array.isArray(body.data)) return body.data;
+  }
+  return [];
+}
+
+function itemLeaf(item) {
+  const raw = String(item?.name ?? item?.fileName ?? "").replace(/\/$/, "");
+  const parts = raw.split("/");
+  return parts.at(-1) ?? "";
+}
+
+function isDirectoryItem(item) {
+  if (item?.isDir === true || item?.isDirectory === true) return true;
+  const type = String(item?.type ?? "").toLowerCase();
+  if (type === "dir" || type === "directory") return true;
+  return typeof item?.name === "string" && item.name.endsWith("/");
+}
+
+function itemSize(item) {
+  const n = Number(item?.size ?? item?.fileSize);
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+
+function itemModifiedAt(item) {
+  const t = Date.parse(item?.modified ?? item?.mtime ?? item?.modTime ?? "");
+  return Number.isFinite(t) ? t : 0;
+}
+
+export function findFilesChild(envelope, name) {
+  return filesLsChildren(envelope).find((item) => itemLeaf(item) === name) ?? null;
+}
+
+/**
+ * List one files-backend directory. Identity is already in `process.env`.
+ * @param spawnFn - seam for tests; the real spawn otherwise.
+ */
+export function runOlaresLs(parent, options = {}) {
+  const { signal, spawnFn = spawn } = options;
+  return new Promise((resolve, reject) => {
+    const child = spawnFn("olares-cli", ["files", "ls", parent, "--json"], {
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+      ...(signal ? { signal } : {}),
+    });
+    let stdout = "";
+    let stderr = "";
+    let truncated = false;
+    child.stdout?.on("data", (chunk) => {
+      if (truncated) return;
+      stdout += chunk;
+      if (stdout.length > STDOUT_LIMIT) {
+        truncated = true;
+        stdout = "";
+      }
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr = `${stderr}${chunk}`.slice(-STDERR_LIMIT);
+    });
+    child.on("error", (error) => {
+      reject(lookupError("files_unavailable", `olares-cli files ls failed: ${error.message}`));
+    });
+    child.on("close", (code) => {
+      if (truncated) {
+        reject(lookupError("files_unavailable", "olares-cli files ls output exceeded the read limit"));
+        return;
+      }
+      if (code !== 0) {
+        reject(lookupError(
+          "files_unavailable",
+          `olares-cli files ls exited ${code}: ${stderr.trim() || "no output"}`,
+        ));
+        return;
+      }
+      try {
+        resolve(JSON.parse(stdout));
+      } catch {
+        reject(lookupError("files_unavailable", "olares-cli files ls returned invalid JSON"));
+      }
+    });
+  });
+}
+
+/**
+ * Stat one files-backend file by listing its parent and matching the leaf.
+ * Direct GET of the file URL can 500; parent `ls` is the supported probe.
+ */
+export async function statFilesFile(source, options = {}) {
+  const path = parseFilesPath(source);
+  const cut = path.lastIndexOf("/");
+  const parent = path.slice(0, cut);
+  const name = path.slice(cut + 1);
+  const envelope = await (options.ls ?? runOlaresLs)(parent, options);
+  const item = findFilesChild(envelope, name);
+  if (!item) throw lookupError("file_not_found", `${path} was not found`);
+  if (isDirectoryItem(item)) throw lookupError("path_not_file", `${path} is not a regular file`);
+  return {
+    path,
+    name,
+    size: itemSize(item),
+    modifiedAt: itemModifiedAt(item),
+  };
+}