@rivus/gateway 0.16.2

package/templates/a-share-policy-evidence.mjs

@@ -0,0 +1,145 @@
+import { readAShareProviderResponse } from "./a-share-provider-response.mjs";
+
+const LOOKBACK_MS = 3 * 24 * 60 * 60 * 1000;
+
+export async function readASharePolicyEvidence({ occurrence }) {
+  const occurrenceTime = Date.parse(occurrence);
+  const readers = [
+    { read: readPbcHeadlines, source: "中国人民银行" },
+    { read: readCsrcHeadlines, source: "中国证监会" }
+  ];
+  const settled = await Promise.allSettled(readers.map(({ read }) => read()));
+  const available = settled.flatMap((result, index) =>
+    result.status === "fulfilled" ? [{ items: result.value, source: readers[index].source }] : []
+  );
+  if (available.length === 0) throw new Error("a-share policy evidence sources are unavailable");
+  const items = available
+    .flatMap(({ items }) => items)
+    .filter(({ publishedAt }) => {
+      const publishedTime = Date.parse(publishedAt);
+      return publishedTime <= occurrenceTime && publishedTime >= occurrenceTime - LOOKBACK_MS;
+    })
+    .sort((left, right) => right.publishedAt.localeCompare(left.publishedAt))
+    .slice(0, 4);
+  const sources = available.map(({ source }) => source);
+  const unavailableSources = settled.flatMap((result, index) =>
+    result.status === "rejected" ? [readers[index].source] : []
+  );
+  return Object.freeze({
+    items: Object.freeze(items),
+    sources: Object.freeze(sources),
+    unavailableSources: Object.freeze(unavailableSources)
+  });
+}
+
+async function readPbcHeadlines() {
+  const url = new URL("https://www.pbc.gov.cn/goutongjiaoliu/113456/113469/index.html");
+  const body = await readText(url, "中国人民银行");
+  const items = [];
+  const pattern =
+    /<a\s+([^>]*\bistitle="true"[^>]*)>[\s\S]*?<\/a>\s*<\/font>\s*<span[^>]*>\s*(\d{4}-\d{2}-\d{2})\s*<\/span>/giu;
+  for (const match of body.matchAll(pattern)) {
+    const href = readHtmlAttribute(match[1], "href");
+    const title = decodeHtml(readHtmlAttribute(match[1], "title"));
+    if (!href || !title || title.length > 200) continue;
+    const itemUrl = normalizeSourceUrl(href, url, "www.pbc.gov.cn");
+    if (!itemUrl) continue;
+    items.push(
+      Object.freeze({
+        publishedAt: readPbcPublishedAt(itemUrl, match[2]),
+        source: "中国人民银行",
+        title,
+        url: itemUrl
+      })
+    );
+    if (items.length === 2) break;
+  }
+  if (items.length === 0) throw new Error("PBC policy evidence contains no valid headlines");
+  return Object.freeze(items);
+}
+
+function readPbcPublishedAt(itemUrl, displayedDate) {
+  const timestamp = new URL(itemUrl).pathname.match(/\/(\d{14})\d*\/index\.html$/u)?.[1];
+  if (!timestamp) return `${displayedDate}T23:59:59+08:00`;
+  return `${timestamp.replace(/^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})$/u, "$1-$2-$3T$4:$5:$6")}+08:00`;
+}
+
+async function readCsrcHeadlines() {
+  const url = new URL("https://www.csrc.gov.cn/searchList/a1a078ee0bc54721ab6b148884c784a8");
+  url.searchParams.set("_isAgg", "true");
+  url.searchParams.set("_isJson", "true");
+  url.searchParams.set("_pageSize", "5");
+  url.searchParams.set("_template", "index");
+  url.searchParams.set("_rangeTimeGte", "");
+  url.searchParams.set("_channelName", "");
+  url.searchParams.set("page", "1");
+  const body = await readText(url, "中国证监会", 256 * 1024);
+  let payload;
+  try {
+    payload = JSON.parse(body);
+  } catch (cause) {
+    throw new Error("CSRC policy evidence is not valid JSON", { cause });
+  }
+  const results = Array.isArray(payload?.data?.results) ? payload.data.results : undefined;
+  if (!results) throw new Error("CSRC policy evidence contains no result list");
+  const items = results
+    .flatMap((row) => {
+      if (
+        typeof row?.title !== "string" ||
+        !row.title ||
+        row.title.length > 200 ||
+        typeof row?.url !== "string" ||
+        !/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(row?.publishedTimeStr ?? "")
+      ) {
+        return [];
+      }
+      const itemUrl = normalizeSourceUrl(row.url, url, "www.csrc.gov.cn");
+      if (!itemUrl) return [];
+      return [
+        Object.freeze({
+          publishedAt: `${row.publishedTimeStr.replace(" ", "T")}+08:00`,
+          source: "中国证监会",
+          title: row.title,
+          url: itemUrl
+        })
+      ];
+    })
+    .slice(0, 2);
+  if (items.length === 0) throw new Error("CSRC policy evidence contains no valid headlines");
+  return Object.freeze(items);
+}
+
+async function readText(url, source, maxBytes = 128 * 1024) {
+  const body = await readAShareProviderResponse({
+    accept: "text/html,application/json",
+    maxBytes,
+    referer: `${url.origin}/`,
+    source: `${source} policy evidence`,
+    url
+  });
+  return body.toString("utf8");
+}
+
+function readHtmlAttribute(attributes, name) {
+  return attributes.match(new RegExp(`\\b${name}="([^"]+)"`, "iu"))?.[1];
+}
+
+function normalizeSourceUrl(value, baseUrl, expectedHostname) {
+  let url;
+  try {
+    url = new URL(value, baseUrl);
+  } catch {
+    return undefined;
+  }
+  if (url.protocol !== "https:" || url.hostname !== expectedHostname) return undefined;
+  return url.href;
+}
+
+function decodeHtml(value) {
+  return value
+    .replaceAll("&amp;", "&")
+    .replaceAll("&quot;", '"')
+    .replaceAll("&#39;", "'")
+    .replaceAll("&lt;", "<")
+    .replaceAll("&gt;", ">");
+}

package/templates/a-share-provider-response.mjs

@@ -0,0 +1,21 @@
+import { readBoundedHttpsResponse } from "./https-response-reader.mjs";
+
+export async function readAShareProviderResponse({ accept, maxBytes, referer, source, url }) {
+  let response;
+  try {
+    response = await readBoundedHttpsResponse(url, {
+      headers: {
+        accept,
+        referer,
+        "user-agent": "rivus-a-share-market-briefing/1.1"
+      },
+      maxBytes
+    });
+  } catch (cause) {
+    throw new Error(`${source} request failed`, { cause });
+  }
+  if (response.status < 200 || response.status >= 300) {
+    throw new Error(`${source} request failed with HTTP ${response.status}`);
+  }
+  return response.body;
+}

package/templates/a-share-sector-evidence.mjs

@@ -0,0 +1,70 @@
+import { dateInShanghai } from "./a-share-market-date.mjs";
+import { readAShareProviderResponse } from "./a-share-provider-response.mjs";
+
+const SOURCE = "东方财富行业板块公开行情";
+
+export async function readAShareSectorEvidence({ marketDate }) {
+  const [leaders, laggards] = await Promise.all([readSectorRanking(true), readSectorRanking(false)]);
+  const sectors = [...leaders, ...laggards];
+  const asOf = sectors
+    .map(({ asOf }) => asOf)
+    .sort((left, right) => left.localeCompare(right))
+    .at(-1);
+  if (!sectors.every((sector) => dateInShanghai(new Date(sector.asOf)) === marketDate)) {
+    throw new Error("a-share sector evidence is stale for the market date");
+  }
+  return Object.freeze({ asOf, laggards, leaders, source: SOURCE });
+}
+
+async function readSectorRanking(descending) {
+  const url = new URL("https://push2delay.eastmoney.com/api/qt/clist/get");
+  url.searchParams.set("pn", "1");
+  url.searchParams.set("pz", "3");
+  url.searchParams.set("po", descending ? "1" : "0");
+  url.searchParams.set("np", "1");
+  url.searchParams.set("fltt", "2");
+  url.searchParams.set("invt", "2");
+  url.searchParams.set("fid", "f3");
+  url.searchParams.set("fs", "m:90+t:2");
+  url.searchParams.set("fields", "f12,f14,f3,f124");
+  const body = await readAShareProviderResponse({
+    accept: "application/json",
+    maxBytes: 64 * 1024,
+    referer: "https://quote.eastmoney.com/",
+    source: "a-share sector evidence",
+    url
+  });
+  return parseSectorRanking(body.toString("utf8"));
+}
+
+function parseSectorRanking(body) {
+  let payload;
+  try {
+    payload = JSON.parse(body);
+  } catch (cause) {
+    throw new Error("a-share sector evidence is not valid JSON", { cause });
+  }
+  const rows = payload?.rc === 0 && Array.isArray(payload?.data?.diff) ? payload.data.diff : undefined;
+  if (!rows || rows.length !== 3) throw new Error("a-share sector evidence must contain three ranked industries");
+  return Object.freeze(
+    rows.map((row) => {
+      if (
+        typeof row?.f12 !== "string" ||
+        !row.f12 ||
+        typeof row?.f14 !== "string" ||
+        !row.f14 ||
+        !Number.isFinite(row?.f3) ||
+        !Number.isSafeInteger(row?.f124) ||
+        row.f124 <= 0
+      ) {
+        throw new Error("a-share sector evidence contains an invalid industry record");
+      }
+      return Object.freeze({
+        asOf: new Date(row.f124 * 1000).toISOString(),
+        changePercent: row.f3,
+        id: row.f12,
+        name: row.f14
+      });
+    })
+  );
+}

package/templates/acp-stdio-proxy.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+import {
+  createAcpAgentServer,
+  createAcpPermissionBridge,
+  createAcpStdioAgentLoop,
+  createJsonAcpSessionStore,
+  serveAcpAgentOnStdio
+} from "@rivus/agent/acp";
+
+const command = process.env.RIVUS_ACP_SERVER_COMMAND?.trim();
+if (!command) throw new Error("RIVUS_ACP_SERVER_COMMAND is required and must resolve to an explicit executable");
+
+const workingDirectory = process.env.RIVUS_ACP_WORKING_DIRECTORY?.trim() || process.cwd();
+const sessionStorePath = process.env.RIVUS_ACP_SESSION_STORE?.trim();
+const permissionBridge = createAcpPermissionBridge();
+const downstream = createAcpStdioAgentLoop({
+  arguments: parseArguments(process.env.RIVUS_ACP_SERVER_ARGUMENTS),
+  command,
+  environment: selectEnvironment(process.env.RIVUS_ACP_SERVER_ENV_KEYS),
+  onStderr: (text) => process.stderr.write(text),
+  permissionPolicy: permissionBridge.policy,
+  ...(sessionStorePath ? { sessionStore: createJsonAcpSessionStore({ filePath: sessionStorePath }) } : {}),
+  workingDirectory
+});
+const server = createAcpAgentServer({
+  agentName: "rivus-acp-proxy",
+  loop: downstream.loop,
+  permissionBridge,
+  workingDirectory
+});
+
+try {
+  await serveAcpAgentOnStdio(server);
+} finally {
+  await downstream.dispose();
+}
+
+function parseArguments(value) {
+  if (!value?.trim()) return [];
+  const parsed = JSON.parse(value);
+  if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== "string")) {
+    throw new Error("RIVUS_ACP_SERVER_ARGUMENTS must be a JSON array of strings");
+  }
+  return parsed;
+}
+
+function selectEnvironment(value) {
+  const selected = {};
+  for (const key of value
+    ?.split(",")
+    .map((item) => item.trim())
+    .filter(Boolean) ?? []) {
+    const environmentValue = process.env[key];
+    if (environmentValue !== undefined) selected[key] = environmentValue;
+  }
+  return selected;
+}

package/templates/current-weather.mjs

@@ -0,0 +1,117 @@
+import { readBoundedHttpsResponse } from "./https-response-reader.mjs";
+
+export async function readCurrentWeather(input) {
+  if (input !== undefined && (typeof input !== "object" || input === null || Array.isArray(input))) {
+    throw new Error("current-weather input must be an object");
+  }
+  const requestedLocation = input?.location;
+  if (
+    requestedLocation !== undefined &&
+    (typeof requestedLocation !== "string" || !requestedLocation.trim() || requestedLocation.length > 100)
+  ) {
+    throw new Error("current-weather location must be a non-empty string up to 100 characters");
+  }
+  const location = requestedLocation?.trim() || process.env.RIVUS_WEATHER_DEFAULT_LOCATION?.trim() || "北京";
+  const geocodingUrl = new URL("https://geocoding-api.open-meteo.com/v1/search");
+  geocodingUrl.search = new URLSearchParams({ count: "1", format: "json", language: "zh", name: location }).toString();
+  const geocoding = await fetchJson(geocodingUrl, "weather location lookup");
+  const place = Array.isArray(geocoding.results) ? geocoding.results[0] : undefined;
+  if (
+    !place ||
+    typeof place.name !== "string" ||
+    typeof place.latitude !== "number" ||
+    typeof place.longitude !== "number"
+  ) {
+    throw new Error(`current-weather could not resolve location: ${location}`);
+  }
+
+  const forecastUrl = new URL("https://api.open-meteo.com/v1/forecast");
+  forecastUrl.search = new URLSearchParams({
+    current: "temperature_2m,apparent_temperature,weather_code,wind_speed_10m",
+    daily: "temperature_2m_max,temperature_2m_min,precipitation_probability_max",
+    forecast_days: "1",
+    latitude: String(place.latitude),
+    longitude: String(place.longitude),
+    timezone: "auto"
+  }).toString();
+  const forecast = await fetchJson(forecastUrl, "weather forecast lookup");
+  const current = forecast.current;
+  const daily = forecast.daily;
+  if (!current || typeof current !== "object" || !daily || typeof daily !== "object") {
+    throw new Error("current-weather provider returned an incomplete forecast");
+  }
+  const weatherCode = readNumber(current.weather_code, "weather_code");
+  return {
+    apparentTemperatureC: readNumber(current.apparent_temperature, "apparent_temperature"),
+    condition: describeWeatherCode(weatherCode),
+    date: readFirst(daily.time, "date"),
+    location: place.country ? `${place.name}, ${place.country}` : place.name,
+    observedAt: readString(current.time, "observed time"),
+    precipitationProbabilityPercent: readFirstNumber(daily.precipitation_probability_max, "precipitation probability"),
+    temperatureC: readNumber(current.temperature_2m, "temperature"),
+    temperatureMaxC: readFirstNumber(daily.temperature_2m_max, "maximum temperature"),
+    temperatureMinC: readFirstNumber(daily.temperature_2m_min, "minimum temperature"),
+    timezone: readString(forecast.timezone ?? place.timezone, "timezone"),
+    weatherCode,
+    windSpeedKmh: readNumber(current.wind_speed_10m, "wind speed")
+  };
+}
+
+async function fetchJson(url, operation) {
+  let response;
+  try {
+    response = await readBoundedHttpsResponse(url, {
+      headers: { accept: "application/json" },
+      maxBytes: 1024 * 1024
+    });
+  } catch (error) {
+    throw new Error(`${operation} failed: ${error instanceof Error ? error.message : String(error)}`, {
+      cause: error
+    });
+  }
+  if (response.status < 200 || response.status >= 300) {
+    throw new Error(`${operation} failed with HTTP ${response.status}`);
+  }
+  let value;
+  try {
+    value = JSON.parse(response.body.toString("utf8"));
+  } catch {
+    throw new Error(`${operation} returned invalid JSON`);
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${operation} returned invalid JSON`);
+  }
+  return value;
+}
+
+function readNumber(value, field) {
+  if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`current-weather missing ${field}`);
+  return value;
+}
+
+function readString(value, field) {
+  if (typeof value !== "string" || !value) throw new Error(`current-weather missing ${field}`);
+  return value;
+}
+
+function readFirst(value, field) {
+  return readString(Array.isArray(value) ? value[0] : undefined, field);
+}
+
+function readFirstNumber(value, field) {
+  return readNumber(Array.isArray(value) ? value[0] : undefined, field);
+}
+
+function describeWeatherCode(code) {
+  if (code === 0) return "晴";
+  if (code === 1 || code === 2) return "晴间多云";
+  if (code === 3) return "阴";
+  if (code === 45 || code === 48) return "有雾";
+  if (code >= 51 && code <= 57) return "毛毛雨";
+  if (code >= 61 && code <= 67) return "雨";
+  if (code >= 71 && code <= 77) return "雪";
+  if (code >= 80 && code <= 82) return "阵雨";
+  if (code >= 85 && code <= 86) return "阵雪";
+  if (code >= 95 && code <= 99) return "雷暴";
+  return "未知";
+}

package/templates/html-drive-tools.mjs

@@ -0,0 +1,262 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, mkdtemp, open, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const DEFAULT_ARTIFACT_ROOT = ".rivus/deployment/html-artifacts";
+
+export function createHtmlArtifactWriter(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const artifactRoot = resolveArtifactRoot(cwd, options.artifactRoot);
+  return {
+    async execute(input, context) {
+      const html = readCompleteHtml(input);
+      const operationId = readOperationId(context);
+      const agentDirectory = resolveAgentDirectory(artifactRoot, context?.agentId);
+      const artifactId = createHash("sha256")
+        .update(JSON.stringify({ agentId: context.agentId, operationId }))
+        .digest("hex")
+        .slice(0, 32);
+      const trustedDirectory = await createTrustedDirectory(cwd, agentDirectory);
+      const filePath = resolve(trustedDirectory, `${artifactId}.html`);
+      try {
+        await writeFile(filePath, html, { encoding: "utf8", flag: "wx" });
+      } catch (error) {
+        if (!isFileAlreadyPresent(error) || (await readFile(filePath, "utf8")) !== html) throw error;
+      }
+      return Object.freeze({
+        artifactId,
+        path: relative(cwd, resolve(agentDirectory, `${artifactId}.html`)),
+        sha256: createHash("sha256").update(html).digest("hex"),
+        size: Buffer.byteLength(html)
+      });
+    }
+  };
+}
+
+export function createLarkDriveHtmlUploader(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const artifactRoot = resolveArtifactRoot(cwd, options.artifactRoot);
+  const onCleanupError = options.onCleanupError ?? reportCleanupError;
+  const removeDirectory = options.removeDirectory ?? rm;
+  const runCommand = options.runCommand ?? runLarkCli;
+  return {
+    async execute(input, context) {
+      readOperationId(context);
+      const { artifactId, name } = readUploadInput(input);
+      const agentDirectory = resolveAgentDirectory(artifactRoot, context?.agentId);
+      const trustedDirectory = await resolveExistingTrustedDirectory(cwd, agentDirectory);
+      const filePath = resolve(trustedDirectory, `${artifactId}.html`);
+      const bytes = await readRegularFileNoFollow(filePath, artifactId);
+      const stagingRoot = resolve(cwd, ".rivus/deployment/upload-staging");
+      const trustedStagingRoot = await createTrustedDirectory(cwd, stagingRoot);
+      const trustedWorkspace = await realpath(cwd);
+      const stagingDirectory = await mkdtemp(join(trustedStagingRoot, "upload-"));
+      const stagedPath = resolve(stagingDirectory, name);
+      try {
+        await writeFile(stagedPath, bytes, { flag: "wx", mode: 0o600 });
+        const command = process.env.RIVUS_LARK_CLI_PATH?.trim() || "lark-cli";
+        const { stdout } = await runCommand(
+          command,
+          [
+            "drive",
+            "+upload",
+            "--as",
+            "user",
+            "--file",
+            relative(trustedWorkspace, stagedPath),
+            "--name",
+            name,
+            "--format",
+            "json"
+          ],
+          { cwd, timeout: 120_000 }
+        );
+        return readUploadResult(stdout, name);
+      } finally {
+        await cleanupStaging(removeDirectory, onCleanupError, stagingDirectory);
+      }
+    }
+  };
+}
+
+async function readRegularFileNoFollow(filePath, artifactId) {
+  const linkMetadata = await lstat(filePath);
+  if (linkMetadata.isSymbolicLink()) throw new Error(`HTML artifact cannot be a symbolic link: ${artifactId}`);
+  if (typeof constants.O_NOFOLLOW !== "number") {
+    throw new Error("HTML artifact upload requires filesystem no-follow support");
+  }
+  const handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const metadata = await handle.stat();
+    if (!metadata.isFile()) throw new Error(`HTML artifact is not a regular file: ${artifactId}`);
+    if (metadata.size > 256 * 1024) throw new Error(`HTML artifact exceeds the 256 KiB limit: ${artifactId}`);
+    return await handle.readFile();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function cleanupStaging(removeDirectory, onCleanupError, stagingDirectory) {
+  try {
+    await removeDirectory(stagingDirectory, { force: true, recursive: true });
+  } catch (error) {
+    try {
+      onCleanupError(error);
+    } catch {
+      // Cleanup diagnostics must not change the known remote upload outcome.
+    }
+  }
+}
+
+function reportCleanupError(error) {
+  process.emitWarning(
+    `Could not remove the private HTML upload staging directory: ${error instanceof Error ? error.message : String(error)}`
+  );
+}
+
+async function runLarkCli(command, args, options) {
+  return execFileAsync(command, args, {
+    ...options,
+    env: {
+      ...process.env,
+      LARKSUITE_CLI_NO_SKILLS_NOTIFIER: "1",
+      LARKSUITE_CLI_NO_UPDATE_NOTIFIER: "1"
+    },
+    maxBuffer: 1024 * 1024
+  });
+}
+
+function readCompleteHtml(input) {
+  if (!isRecord(input) || typeof input.html !== "string") {
+    throw new Error("write-html-artifact requires an html string");
+  }
+  const html = input.html.trim();
+  if (!/^<!doctype html>/i.test(html) || !/<html(?:\s|>)/i.test(html) || !/<\/html>\s*$/i.test(html)) {
+    throw new Error("write-html-artifact requires a complete HTML document");
+  }
+  if (Buffer.byteLength(html) > 256 * 1024) throw new Error("HTML artifact exceeds the 256 KiB limit");
+  return html;
+}
+
+function readUploadInput(input) {
+  if (!isRecord(input) || typeof input.artifactId !== "string" || !/^[a-f0-9]{32}$/.test(input.artifactId)) {
+    throw new Error("lark-drive-upload-html requires a valid artifactId");
+  }
+  if (
+    typeof input.name !== "string" ||
+    !/^[^/\\]{1,120}\.html$/i.test(input.name) ||
+    input.name === ".html" ||
+    input.name.includes("..")
+  ) {
+    throw new Error("lark-drive-upload-html requires a safe .html file name");
+  }
+  return { artifactId: input.artifactId, name: input.name };
+}
+
+function readUploadResult(stdout, requestedName) {
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    throw new Error("lark-cli upload returned invalid JSON");
+  }
+  const result = isRecord(parsed?.data) ? parsed.data : parsed;
+  if (!isRecord(result)) throw new Error("lark-cli upload returned an invalid result");
+  const fileToken = readFirstString(result, ["file_token", "fileToken", "token"]);
+  const url = readFirstString(result, ["url", "web_url", "file_url"]);
+  const name = readFirstString(result, ["name", "file_name"]) ?? requestedName;
+  if (!fileToken || !url) throw new Error("lark-cli upload result is missing file token or URL");
+  return Object.freeze({ fileToken, name, url });
+}
+
+function readFirstString(value, keys) {
+  for (const key of keys) {
+    const candidate = value[key];
+    if (typeof candidate === "string" && candidate.trim()) return candidate.trim();
+  }
+  return undefined;
+}
+
+function resolveArtifactRoot(cwd, artifactRoot = DEFAULT_ARTIFACT_ROOT) {
+  const root = resolve(cwd, artifactRoot);
+  const relativeRoot = relative(cwd, root);
+  if (relativeRoot === ".." || relativeRoot.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)) {
+    throw new Error("HTML artifact root must stay inside the workspace");
+  }
+  return root;
+}
+
+function resolveAgentDirectory(artifactRoot, agentId) {
+  if (typeof agentId !== "string" || !agentId.trim()) throw new Error("HTML artifact tool requires an agent id");
+  return resolve(artifactRoot, createHash("sha256").update(agentId).digest("hex").slice(0, 16));
+}
+
+async function createTrustedDirectory(cwd, directory) {
+  return resolveTrustedDirectory(cwd, directory, true);
+}
+
+async function resolveExistingTrustedDirectory(cwd, directory) {
+  return resolveTrustedDirectory(cwd, directory, false);
+}
+
+async function resolveTrustedDirectory(cwd, directory, create) {
+  const lexicalWorkspace = resolve(cwd);
+  const lexicalDirectory = resolve(directory);
+  const lexicalRelativePath = relative(lexicalWorkspace, lexicalDirectory);
+  if (lexicalRelativePath === ".." || lexicalRelativePath.startsWith(`..${sep}`)) {
+    throw new Error("HTML artifact directory must stay inside the workspace");
+  }
+  const segments = lexicalRelativePath.split(sep).filter(Boolean);
+  let current = lexicalWorkspace;
+  for (const segment of segments) {
+    current = resolve(current, segment);
+    const metadata = await readOrCreateDirectory(current, create);
+    if (metadata.isSymbolicLink()) {
+      throw new Error("HTML artifact directory cannot contain symbolic links");
+    }
+    if (!metadata.isDirectory()) throw new Error("HTML artifact path component is not a directory");
+  }
+  const [workspacePath, directoryPath] = await Promise.all([realpath(lexicalWorkspace), realpath(lexicalDirectory)]);
+  const resolvedRelativePath = relative(workspacePath, directoryPath);
+  if (resolvedRelativePath === ".." || resolvedRelativePath.startsWith(`..${sep}`)) {
+    throw new Error("HTML artifact directory resolved outside the workspace");
+  }
+  return directoryPath;
+}
+
+async function readOrCreateDirectory(directory, create) {
+  try {
+    return await lstat(directory);
+  } catch (error) {
+    if (!isMissingFile(error) || !create) throw error;
+  }
+  try {
+    await mkdir(directory);
+  } catch (error) {
+    if (!isFileAlreadyPresent(error)) throw error;
+  }
+  return lstat(directory);
+}
+
+function readOperationId(context) {
+  if (typeof context?.operationId !== "string" || !context.operationId.trim()) {
+    throw new Error("HTML artifact tool requires a stable operation id");
+  }
+  return context.operationId;
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isFileAlreadyPresent(error) {
+  return error instanceof Error && "code" in error && error.code === "EEXIST";
+}
+
+function isMissingFile(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}