@rivus/agent 0.16.6 → 0.17.0

package/examples/html-drive-tools.mjs

@@ -1,262 +0,0 @@
-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";
-}

package/examples/https-response-reader.mjs

@@ -1,36 +0,0 @@
-import { get } from "node:https";
-
-export function readBoundedHttpsResponse(url, options) {
-  return new Promise((resolve, reject) => {
-    const request = get(
-      url,
-      {
-        family: 4,
-        headers: options.headers,
-        signal: AbortSignal.timeout(options.timeoutMs ?? 10_000)
-      },
-      (response) => {
-        const status = response.statusCode ?? 0;
-        response.once("error", reject);
-        if (status < 200 || status >= 300) {
-          response.resume();
-          resolve({ body: Buffer.alloc(0), status });
-          return;
-        }
-        const chunks = [];
-        let length = 0;
-        response.on("data", (chunk) => {
-          const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-          length += buffer.length;
-          if (length > options.maxBytes) {
-            request.destroy(new Error(`HTTPS response exceeds ${options.maxBytes} bytes`));
-            return;
-          }
-          chunks.push(buffer);
-        });
-        response.once("end", () => resolve({ body: Buffer.concat(chunks), status }));
-      }
-    );
-    request.once("error", reject);
-  });
-}

package/examples/langfuse-drive-e2e.mjs

@@ -1,175 +0,0 @@
-import { execFile } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { promisify } from "node:util";
-
-import { runLangfuseDriveE2E } from "../dist/testing/index.js";
-
-const execFileAsync = promisify(execFile);
-const baseUrl = requiredEnv("LANGFUSE_BASE_URL");
-const publicKey = requiredEnv("LANGFUSE_PUBLIC_KEY");
-const secretKey = requiredEnv("LANGFUSE_SECRET_KEY");
-const marker = `${new Date()
-  .toISOString()
-  .replace(/[^0-9]/g, "")
-  .slice(0, 14)}-${randomUUID().slice(0, 8)}`;
-const sessionKey = `e2e:langfuse-drive:${marker}`;
-const expectedDriveTitle = `langfuse-e2e-${marker}.html`;
-const discoveredTraceIds = new Set();
-const deploymentStateDirectory = await mkdtemp(join(tmpdir(), "rivus-langfuse-e2e-state-"));
-const prompt = [
-  "Read the granted Langfuse HTML publishing Skill.",
-  "Create a polished, accessible, self-contained Chinese Langfuse introduction page.",
-  `Include the visible E2E marker ${marker}, then upload it as ${expectedDriveTitle}.`,
-  "Return the verified Feishu Drive URL."
-].join(" ");
-
-const result = await runLangfuseDriveE2E({
-  dependencies: {
-    inspectDrive: async (url) => {
-      const output = await command(process.env.RIVUS_LARK_CLI_PATH?.trim() || "lark-cli", [
-        "drive",
-        "+inspect",
-        "--as",
-        "user",
-        "--url",
-        url,
-        "--format",
-        "json"
-      ]);
-      const parsed = JSON.parse(output);
-      return isRecord(parsed.data) ? parsed.data : parsed;
-    },
-    listObservations: async ({ deadlineAt, fromStartTime, sessionKey: expectedSessionKey, toStartTime }) => {
-      if (discoveredTraceIds.size === 0) {
-        let cursor;
-        do {
-          const endpoint = new URL("/api/public/v2/observations", baseUrl);
-          endpoint.searchParams.set("fields", "core,basic");
-          endpoint.searchParams.set("fromStartTime", fromStartTime);
-          endpoint.searchParams.set("limit", "1000");
-          endpoint.searchParams.set("toStartTime", toStartTime);
-          if (cursor) endpoint.searchParams.set("cursor", cursor);
-          const body = await fetchLangfuseJson(endpoint, deadlineAt);
-          if (!isRecord(body) || !Array.isArray(body.data))
-            throw new Error("Langfuse returned an invalid observation page");
-          for (const observation of body.data.filter(isObservation)) {
-            if (observation.sessionId === expectedSessionKey) discoveredTraceIds.add(observation.traceId);
-          }
-          cursor = isRecord(body.meta) && typeof body.meta.cursor === "string" ? body.meta.cursor : undefined;
-        } while (cursor && discoveredTraceIds.size === 0);
-      }
-      const traces = [];
-      for (const traceId of [...discoveredTraceIds].slice(0, 4)) {
-        traces.push(await fetchLangfuseJson(new URL(`/api/public/traces/${traceId}`, baseUrl), deadlineAt));
-      }
-      return traces.flatMap((trace) => {
-        if (
-          !isRecord(trace) ||
-          typeof trace.id !== "string" ||
-          typeof trace.sessionId !== "string" ||
-          !Array.isArray(trace.observations)
-        )
-          return [];
-        return trace.observations.filter(isTraceObservation).map((observation) => ({
-          ...observation,
-          sessionId: trace.sessionId,
-          traceId: trace.id
-        }));
-      });
-    },
-    now: () => new Date(),
-    readDriveFile: async (fileToken) => {
-      const directory = await mkdtemp(join(tmpdir(), "rivus-langfuse-drive-e2e-"));
-      const outputName = `./${expectedDriveTitle}`;
-      try {
-        await command(
-          process.env.RIVUS_LARK_CLI_PATH?.trim() || "lark-cli",
-          ["drive", "+download", "--as", "user", "--file-token", fileToken, "--output", outputName],
-          directory
-        );
-        return await readFile(join(directory, expectedDriveTitle), "utf8");
-      } finally {
-        await rm(directory, { force: true, recursive: true });
-      }
-    },
-    runAgent: ({ prompt: agentPrompt, sessionKey: agentSessionKey }) =>
-      command(
-        process.execPath,
-        [
-          "dist/cli.js",
-          "--bootstrap",
-          "./examples/pi-feishu-deployment.bootstrap.ts",
-          "--manifest",
-          "./examples/rivus-langfuse-demo.config.json",
-          "--prompt",
-          agentPrompt,
-          "--session-key",
-          agentSessionKey
-        ],
-        process.cwd(),
-        { RIVUS_DEPLOYMENT_STATE_DIR: deploymentStateDirectory }
-      ),
-    sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds))
-  },
-  expectedDriveContentMarker: marker,
-  expectedDriveTitle,
-  prompt,
-  sessionKey
-}).finally(() => rm(deploymentStateDirectory, { force: true, recursive: true }));
-
-process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-
-async function fetchLangfuseJson(endpoint, deadlineAt) {
-  const remainingMs = new Date(deadlineAt).getTime() - Date.now();
-  if (!Number.isFinite(remainingMs) || remainingMs <= 0) throw new Error("Langfuse request deadline expired");
-  const response = await fetch(endpoint, {
-    headers: {
-      authorization: `Basic ${Buffer.from(`${publicKey}:${secretKey}`).toString("base64")}`
-    },
-    signal: AbortSignal.timeout(Math.min(remainingMs, 10_000))
-  });
-  if (!response.ok) throw new Error(`Langfuse request failed with HTTP ${response.status}`);
-  return response.json();
-}
-
-async function command(executable, args, cwd = process.cwd(), extraEnv = {}) {
-  const { stdout } = await execFileAsync(executable, args, {
-    cwd,
-    env: {
-      ...process.env,
-      ...extraEnv,
-      LARKSUITE_CLI_NO_SKILLS_NOTIFIER: "1",
-      LARKSUITE_CLI_NO_UPDATE_NOTIFIER: "1"
-    },
-    maxBuffer: 2 * 1024 * 1024,
-    timeout: 300_000
-  });
-  return stdout;
-}
-
-function requiredEnv(name) {
-  const value = process.env[name]?.trim();
-  if (!value) throw new Error(`${name} is required`);
-  return value;
-}
-
-function isObservation(value) {
-  return isTraceObservation(value) && typeof value.traceId === "string" && typeof value.sessionId === "string";
-}
-
-function isTraceObservation(value) {
-  return (
-    isRecord(value) &&
-    typeof value.id === "string" &&
-    typeof value.name === "string" &&
-    typeof value.startTime === "string" &&
-    typeof value.type === "string"
-  );
-}
-
-function isRecord(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}

package/examples/pi-feishu-deployment.bootstrap.ts

@@ -1,3 +0,0 @@
-// Projects initialized by Gateway keep the historical bootstrap specifier while
-// the implementation remains in the Gateway package canonical owner.
-export { createRivusDeploymentAdapters } from "@rivus/agent/bootstrap/pi-feishu";