@rivus/agent 0.1.0

package/dist/testing/index.d.ts

@@ -0,0 +1,55 @@
+import { a as assertRivusPluginConforms, i as RivusPluginLifecycleProbe, n as RivusPluginConformanceInput, o as createFakeRivusPlugin, r as RivusPluginConformanceReport, t as RivusPluginConformanceError } from "../rivus-plugin-testkit.js";
+
+//#region src/testing/langfuse-drive-e2e.d.ts
+interface LangfuseObservation {
+  readonly id: string;
+  readonly name: string;
+  readonly level?: string;
+  readonly output?: unknown;
+  readonly parentObservationId?: string;
+  readonly sessionId?: string;
+  readonly startTime: string;
+  readonly traceId: string;
+  readonly type: string;
+}
+interface LangfuseObservationWindow {
+  readonly deadlineAt: string;
+  readonly fromStartTime: string;
+  readonly sessionKey: string;
+  readonly toStartTime: string;
+}
+interface LangfuseDriveE2EDependencies {
+  inspectDrive(url: string): Promise<unknown>;
+  listObservations(window: LangfuseObservationWindow): Promise<ReadonlyArray<LangfuseObservation>>;
+  now(): Date;
+  readDriveFile(fileToken: string): Promise<string>;
+  runAgent(input: {
+    readonly prompt: string;
+    readonly sessionKey: string;
+  }): Promise<string>;
+  sleep(milliseconds: number): Promise<void>;
+}
+interface RunLangfuseDriveE2EOptions {
+  readonly dependencies: LangfuseDriveE2EDependencies;
+  readonly expectedDriveContentMarker: string;
+  readonly expectedDriveTitle: string;
+  readonly pollIntervalMs?: number;
+  readonly prompt: string;
+  readonly sessionKey: string;
+  readonly timeoutMs?: number;
+}
+interface LangfuseDriveE2EResult {
+  readonly drive: {
+    readonly title: string;
+    readonly type: "file";
+    readonly url: string;
+  };
+  readonly modelCallCount: number;
+  readonly observationCount: number;
+  readonly observationNames: ReadonlyArray<string>;
+  readonly sessionKey: string;
+  readonly traceId: string;
+}
+declare function runLangfuseDriveE2E(options: RunLangfuseDriveE2EOptions): Promise<LangfuseDriveE2EResult>;
+//#endregion
+export { RivusPluginConformanceError, RivusPluginConformanceInput, RivusPluginConformanceReport, RivusPluginLifecycleProbe, assertRivusPluginConforms, createFakeRivusPlugin, runLangfuseDriveE2E };

package/dist/testing/index.js

@@ -0,0 +1,94 @@
+import { n as assertRivusPluginConforms, r as createFakeRivusPlugin, t as RivusPluginConformanceError } from "../rivus-plugin-testkit.js";
+//#region src/testing/langfuse-drive-e2e.ts
+async function runLangfuseDriveE2E(options) {
+	const timeoutMs = options.timeoutMs ?? 12e4;
+	const pollIntervalMs = options.pollIntervalMs ?? 2e3;
+	const startedAt = options.dependencies.now();
+	const driveUrl = extractDriveFileUrl(await options.dependencies.runAgent({
+		prompt: options.prompt,
+		sessionKey: options.sessionKey
+	}));
+	const drive = readDriveInspection(await options.dependencies.inspectDrive(driveUrl));
+	if (drive.title !== options.expectedDriveTitle) throw new Error(`Feishu Drive title mismatch: expected ${options.expectedDriveTitle}, received ${drive.title}`);
+	if (!(await options.dependencies.readDriveFile(drive.fileToken)).includes(options.expectedDriveContentMarker)) throw new Error("Feishu Drive file does not contain the expected E2E marker");
+	const deadline = options.dependencies.now().getTime() + timeoutMs;
+	while (options.dependencies.now().getTime() <= deadline) {
+		const trace = findCompleteTrace(await options.dependencies.listObservations({
+			deadlineAt: new Date(deadline).toISOString(),
+			fromStartTime: startedAt.toISOString(),
+			sessionKey: options.sessionKey,
+			toStartTime: new Date(options.dependencies.now().getTime() + 6e4).toISOString()
+		}), options.sessionKey, driveUrl);
+		if (trace) return {
+			drive: {
+				title: drive.title,
+				type: "file",
+				url: driveUrl
+			},
+			modelCallCount: trace.observations.filter(({ type }) => type === "GENERATION").length,
+			observationCount: trace.observations.length,
+			observationNames: trace.observations.map(({ name }) => name),
+			sessionKey: options.sessionKey,
+			traceId: trace.traceId
+		};
+		await options.dependencies.sleep(pollIntervalMs);
+	}
+	throw new Error(`Langfuse trace did not become complete within ${timeoutMs}ms for session ${options.sessionKey}`);
+}
+function extractDriveFileUrl(output) {
+	const match = output.match(/https:\/\/[^\s<>"']+\/file\/[a-zA-Z0-9_-]+/u);
+	if (!match) throw new Error("Agent output does not contain a Feishu Drive file URL");
+	return match[0];
+}
+function readDriveInspection(value) {
+	if (!isRecord(value) || value.type !== "file" || typeof value.title !== "string" || value.title.trim() === "" || typeof value.token !== "string" || value.token.trim() === "") throw new Error("Feishu Drive inspection did not resolve a named file");
+	if (!value.title.toLowerCase().endsWith(".html")) throw new Error("Feishu Drive inspection did not resolve an HTML file");
+	return {
+		fileToken: value.token,
+		title: value.title
+	};
+}
+function findCompleteTrace(observations, sessionKey, driveUrl) {
+	const byTrace = /* @__PURE__ */ new Map();
+	for (const observation of observations) {
+		if (observation.sessionId !== sessionKey) continue;
+		byTrace.set(observation.traceId, [...byTrace.get(observation.traceId) ?? [], observation]);
+	}
+	for (const [traceId, candidates] of byTrace) {
+		const ordered = [...candidates].sort((left, right) => left.startTime.localeCompare(right.startTime));
+		const root = ordered.find(({ name, parentObservationId }) => name === "Agent 执行" && !parentObservationId);
+		const turn = root ? ordered.find(({ name, parentObservationId }) => name === "Agent 处理" && parentObservationId === root.id) : void 0;
+		if (!turn) continue;
+		const sequence = findExpectedSequence(ordered.filter(({ parentObservationId }) => parentObservationId === turn.id));
+		const upload = sequence?.at(-2);
+		if (sequence && upload && upload.level !== "ERROR" && outputContainsDriveFile(upload.output, driveUrl)) return {
+			observations: ordered,
+			traceId
+		};
+	}
+}
+function findExpectedSequence(observations) {
+	const predicates = [
+		({ type }) => type === "GENERATION",
+		({ name, type }) => type === "SPAN" && name.startsWith("技能 · "),
+		({ type }) => type === "GENERATION",
+		({ name, type }) => type === "TOOL" && isToolObservation(name, "write-html-artifact"),
+		({ type }) => type === "GENERATION",
+		({ name, type }) => type === "TOOL" && isToolObservation(name, "lark-drive-upload-html"),
+		({ type }) => type === "GENERATION"
+	];
+	return observations.length === predicates.length && observations.every((observation, index) => predicates[index](observation)) ? observations : void 0;
+}
+function outputContainsDriveFile(output, driveUrl) {
+	const fileToken = driveUrl.slice(driveUrl.lastIndexOf("/") + 1);
+	if (!fileToken) return false;
+	return typeof output === "string" ? output.includes(fileToken) : output !== void 0 && JSON.stringify(output).includes(fileToken);
+}
+function isToolObservation(name, toolName) {
+	return name === toolName || name === `工具调用 · ${toolName}`;
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+//#endregion
+export { RivusPluginConformanceError, assertRivusPluginConforms, createFakeRivusPlugin, runLangfuseDriveE2E };

package/examples/current-weather.mjs

@@ -0,0 +1,143 @@
+import { get } from "node:https";
+
+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 requestJson(url);
+  } 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);
+  } 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 requestJson(url) {
+  return new Promise((resolve, reject) => {
+    const request = get(
+      url,
+      {
+        family: 4,
+        headers: { accept: "application/json" },
+        signal: AbortSignal.timeout(10_000)
+      },
+      (response) => {
+        const status = response.statusCode ?? 0;
+        response.once("error", reject);
+        if (status < 200 || status >= 300) {
+          response.resume();
+          resolve({ body: "", status });
+          return;
+        }
+        let body = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          body += chunk;
+        });
+        response.once("end", () => resolve({ body, status }));
+      }
+    );
+    request.once("error", reject);
+  });
+}
+
+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/examples/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";
+}