@rivus/gateway 0.16.2

package/templates/rivus-agents.plugin.mjs

@@ -0,0 +1,290 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+
+import { readCurrentWeather } from "./current-weather.mjs";
+import { readAShareMarketBriefing } from "./a-share-market-briefing.mjs";
+import { createHtmlArtifactWriter, createLarkDriveHtmlUploader } from "./html-drive-tools.mjs";
+
+const TOOL_IDS = {
+  aShareMarketBriefing: "rivus-example-agents/a-share-market-briefing",
+  currentWeather: "rivus-example-agents/current-weather",
+  larkDriveUploadHtml: "rivus-example-agents/lark-drive-upload-html",
+  runtimeInfo: "rivus-example-agents/runtime-info",
+  saveNote: "rivus-example-agents/save-note",
+  writeHtmlArtifact: "rivus-example-agents/write-html-artifact"
+};
+const AGENT_A_TOOL_IDS = [
+  TOOL_IDS.runtimeInfo,
+  TOOL_IDS.saveNote,
+  TOOL_IDS.currentWeather,
+  TOOL_IDS.aShareMarketBriefing
+];
+const AGENT_B_TOOL_IDS = [TOOL_IDS.runtimeInfo, TOOL_IDS.saveNote, TOOL_IDS.currentWeather];
+const WEATHER_INSTRUCTION =
+  "遇到当前或今日天气问题时必须调用 current-weather；用户未指定地点时不要猜测，省略 location 并在回答中明确说明工具返回的默认地点。";
+const MEMORY_INSTRUCTION =
+  "用户明确要求记住、回忆或遗忘偏好时，必须调用 rivus_memory；propose 会持久化一条可在同 Scope 后续检索的待确认候选，不得声称用户已经确认，也不得声称候选尚未写入。";
+const DAILY_WORD_AUTOMATION_ID = "rivus-example-agents/daily-ielts-word";
+const A_SHARE_PRE_MARKET_AUTOMATION_ID = "rivus-example-agents/a-share-pre-market";
+const A_SHARE_POST_MARKET_AUTOMATION_ID = "rivus-example-agents/a-share-post-market";
+const LANGFUSE_PUBLISHER_SKILL_ID = "rivus-example-agents/langfuse-html-publisher";
+const LANGFUSE_PUBLISHER_SKILL = Object.freeze({
+  content: [
+    "Use this skill when the user asks for a polished HTML page that must be published to Feishu Drive.",
+    "1. Design a responsive, accessible, self-contained HTML document with semantic sections and inline CSS. Do not use external scripts or remote assets.",
+    "2. Call write-html-artifact exactly once with the complete document. Do not claim a file exists before the Tool succeeds.",
+    "3. Read the returned artifactId, then call lark-drive-upload-html exactly once with that artifactId and a descriptive .html file name.",
+    "4. Return the verified Drive URL and a concise summary of the page. A local path alone is not a completed publication.",
+    "5. Treat metrics, timings, costs, evaluations, and execution claims as facts only when a Tool result or supplied trace contains them. Clearly label any illustrative data as synthetic.",
+    "6. For Langfuse technical facts, use this official-doc reference verified on 2026-07-15: Trace is the root execution and Observations are nestable steps (do not claim unlimited nesting); supported Observation types are event, span, generation, agent, tool, chain, retriever, evaluator, embedding, and guardrail. A current Python example imports get_client and uses with langfuse.start_as_current_observation(as_type=..., name=...) plus observation.update(...), followed by langfuse.flush() for short-lived processes. The standard environment variables are LANGFUSE_SECRET_KEY, LANGFUSE_PUBLIC_KEY, and LANGFUSE_BASE_URL. Never use the removed v2 langfuse.trace(), trace.generation(), or trace.span() APIs, and never shorten the credential names to LANGFUSE_SECRET or LANGFUSE_PUBLIC.",
+    "7. Any credential example in the page must use these exact illustrative values: LANGFUSE_SECRET_KEY=sk-lf-... ; LANGFUSE_PUBLIC_KEY=pk-lf-... ; LANGFUSE_BASE_URL=https://jp.cloud.langfuse.com . The values are placeholders, not real credentials.",
+    "Official references: https://langfuse.com/docs/observability/data-model ; https://langfuse.com/docs/observability/features/observation-types ; https://langfuse.com/docs/observability/get-started"
+  ].join("\n"),
+  digest: "sha256:example-langfuse-html-publisher-v5",
+  id: LANGFUSE_PUBLISHER_SKILL_ID,
+  title: "Langfuse HTML publisher",
+  version: "5.0.0"
+});
+
+export default {
+  manifest: {
+    apiVersion: "1",
+    id: "rivus-example-agents",
+    version: "0.1.0"
+  },
+  register(registry) {
+    registry.registerTool({
+      createExecutor: () => ({
+        execute: (_input, context) => ({
+          agentId: context.agentId,
+          instanceId: context.instanceId,
+          policyEpoch: context.policyEpoch,
+          runId: context.runId
+        })
+      }),
+      description: "Read the trusted Rivus runtime identity for the current run",
+      digest: "sha256:example-runtime-info-v1",
+      id: TOOL_IDS.runtimeInfo,
+      idempotency: "none",
+      inputSchema: { additionalProperties: false, properties: {}, type: "object" },
+      risk: "observe",
+      version: "1.0.0"
+    });
+    registry.registerTool({
+      createExecutor: () => ({ execute: saveNote }),
+      description: "Persist a Markdown note in the local Rivus deployment state",
+      digest: "sha256:example-save-note-v1",
+      id: TOOL_IDS.saveNote,
+      idempotency: "required",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          text: { minLength: 1, type: "string" },
+          title: { minLength: 1, type: "string" }
+        },
+        required: ["title", "text"],
+        type: "object"
+      },
+      risk: "irreversible",
+      version: "1.0.0"
+    });
+    registry.registerTool({
+      createExecutor: () => ({ execute: readCurrentWeather }),
+      description:
+        "Read current conditions and today's forecast from Open-Meteo. When location is omitted, use the deployment's configured default location.",
+      digest: "sha256:example-current-weather-v1",
+      id: TOOL_IDS.currentWeather,
+      idempotency: "none",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          location: {
+            description: "City or place name. Omit it when the user did not specify a location.",
+            maxLength: 100,
+            minLength: 1,
+            type: "string"
+          }
+        },
+        type: "object"
+      },
+      risk: "observe",
+      version: "1.0.0"
+    });
+    registry.registerTool({
+      createExecutor: () => ({ execute: readAShareMarketBriefing }),
+      description:
+        "Read a bounded, evidence-backed A-share pre-market or post-market analysis briefing with attributed facts, labeled inferences, source time, and stale-data handling",
+      digest: "sha256:example-a-share-market-briefing-v3",
+      id: TOOL_IDS.aShareMarketBriefing,
+      idempotency: "none",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          occurrence: { format: "date-time", type: "string" },
+          session: { enum: ["pre-market", "post-market"], type: "string" }
+        },
+        required: ["session", "occurrence"],
+        type: "object"
+      },
+      risk: "observe",
+      version: "1.1.0"
+    });
+    registry.registerTool({
+      createExecutor: () => createHtmlArtifactWriter(),
+      description:
+        "Write one complete, self-contained HTML document into the trusted Rivus artifact directory and return its artifactId",
+      digest: "sha256:example-write-html-artifact-v1",
+      id: TOOL_IDS.writeHtmlArtifact,
+      idempotency: "required",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          html: {
+            description: "Complete HTML document beginning with <!doctype html> and ending with </html>",
+            maxLength: 262144,
+            minLength: 100,
+            type: "string"
+          }
+        },
+        required: ["html"],
+        type: "object"
+      },
+      risk: "mutate",
+      version: "1.0.0"
+    });
+    registry.registerTool({
+      createExecutor: () => createLarkDriveHtmlUploader(),
+      description:
+        "Upload a previously generated HTML artifact to the current user's Feishu Drive root by invoking lark-cli",
+      digest: "sha256:example-lark-drive-upload-html-v1",
+      id: TOOL_IDS.larkDriveUploadHtml,
+      idempotency: "required",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          artifactId: {
+            description: "artifactId returned by write-html-artifact",
+            pattern: "^[a-f0-9]{32}$",
+            type: "string"
+          },
+          name: {
+            description: "Safe destination file name ending in .html",
+            maxLength: 125,
+            minLength: 6,
+            pattern: "^[^/\\\\]{1,120}\\.html$",
+            type: "string"
+          }
+        },
+        required: ["artifactId", "name"],
+        type: "object"
+      },
+      risk: "mutate",
+      version: "1.0.0"
+    });
+    registry.registerSkill(LANGFUSE_PUBLISHER_SKILL);
+    registry.registerAgentProfile({
+      displayName: "Rivus Agent A",
+      id: "agent-a",
+      memory: { scopes: ["agent-private"] },
+      model: {},
+      skills: { allow: [] },
+      systemPrompt: `You are Rivus Agent A. Be concise, analytical, and explicit about evidence. ${WEATHER_INSTRUCTION} ${MEMORY_INSTRUCTION}`,
+      tools: { allow: AGENT_A_TOOL_IDS }
+    });
+    registry.registerAgentProfile({
+      displayName: "Rivus Agent B",
+      id: "agent-b",
+      memory: { scopes: ["agent-private"] },
+      model: {},
+      skills: { allow: [] },
+      systemPrompt: `You are Rivus Agent B. Focus on independent verification and clearly state uncertainty. ${WEATHER_INSTRUCTION} ${MEMORY_INSTRUCTION}`,
+      tools: { allow: AGENT_B_TOOL_IDS }
+    });
+    registry.registerAgentProfile({
+      displayName: "Rivus Langfuse publishing demo",
+      id: "langfuse-demo",
+      memory: { scopes: [] },
+      model: {},
+      skills: { allow: [LANGFUSE_PUBLISHER_SKILL_ID] },
+      systemPrompt: [
+        "You are the isolated Rivus Langfuse publishing demo Agent.",
+        `Before planning or publishing, read and follow the granted Skill ${LANGFUSE_PUBLISHER_SKILL_ID}.`,
+        "Use only Tool results and user-provided evidence for factual execution claims."
+      ].join(" "),
+      tools: { allow: [TOOL_IDS.writeHtmlArtifact, TOOL_IDS.larkDriveUploadHtml] }
+    });
+    registry.registerAutomation({
+      createInput: ({ occurrence }) => ({
+        text: [
+          `计划发生时间：${occurrence}。为中文雅思学习者生成且只生成一张今日单词卡。`,
+          "选择一个雅思高频但不太基础的英文单词。",
+          "必须依次包含：单词、英式和美式 IPA、中文发音提示、词性与中文释义、一个雅思语境英文例句及中文翻译、常用搭配、记忆提示。",
+          "最后提供可直接点击收听发音的 Cambridge Dictionary 链接：https://dictionary.cambridge.org/pronunciation/english/<小写单词>。",
+          "使用飞书富文本支持的 Markdown 排版：以二级标题开头，字段名加粗，例句、搭配和记忆提示分段或列表展示，发音链接使用 Markdown 链接语法。不要使用表格，不要解释生成过程，也不要输出多个候选词。"
+        ].join("\n")
+      }),
+      id: DAILY_WORD_AUTOMATION_ID,
+      profileId: "agent-a",
+      requestedSkillIds: [],
+      requestedToolIds: []
+    });
+    registry.registerAutomation(createAShareAutomation(A_SHARE_PRE_MARKET_AUTOMATION_ID, "pre-market"));
+    registry.registerAutomation(createAShareAutomation(A_SHARE_POST_MARKET_AUTOMATION_ID, "post-market"));
+  }
+};
+
+function createAShareAutomation(id, session) {
+  const label = session === "pre-market" ? "盘前" : "盘后";
+  return {
+    createInput: ({ occurrence }) => {
+      const parameters = JSON.stringify({ session, occurrence });
+      return {
+        text: [
+          `计划发生时间：${occurrence}。生成 A 股${label}简报。`,
+          `必须且只调用一次 ${TOOL_IDS.aShareMarketBriefing}，参数严格使用：${parameters}。`,
+          "工具返回的 markdown 字段已区分市场事实和分析推断并列出来源，就是最终交付正文；必须原样输出，不增加开场、解释、预测、荐股、因果归因或任何工具结果之外的数字。",
+          "如果工具失败，不得估算或补全行情，让本次 Automation 明确失败以便按同一 Tick 重试。"
+        ].join("\n")
+      };
+    },
+    id,
+    profileId: "agent-a",
+    requestedSkillIds: [],
+    requestedToolIds: [TOOL_IDS.aShareMarketBriefing]
+  };
+}
+
+async function saveNote(input, context) {
+  if (
+    !input ||
+    typeof input !== "object" ||
+    typeof input.title !== "string" ||
+    !input.title.trim() ||
+    typeof input.text !== "string" ||
+    !input.text.trim() ||
+    !context.operationId
+  ) {
+    throw new Error("save-note requires title, text, and a trusted operation id");
+  }
+  const directory = join(
+    process.cwd(),
+    ".rivus",
+    "deployment",
+    "tool-output",
+    createHash("sha256").update(context.agentId).digest("hex").slice(0, 16)
+  );
+  const fileName = `${context.operationId.replace(/[^a-zA-Z0-9_-]/g, "_")}.md`;
+  const filePath = join(directory, fileName);
+  const content = `# ${input.title.trim()}\n\n${input.text.trim()}\n`;
+  await mkdir(directory, { recursive: true });
+  try {
+    await writeFile(filePath, content, { encoding: "utf8", flag: "wx" });
+  } catch (error) {
+    if (!(error instanceof Error) || !("code" in error) || error.code !== "EEXIST") throw error;
+    if ((await readFile(filePath, "utf8")) !== content) {
+      throw new Error("operation id is already bound to different note content");
+    }
+  }
+  return { path: `.rivus/deployment/tool-output/${fileName}`, saved: true };
+}

package/templates/rivus-langfuse-demo.config.json

@@ -0,0 +1,37 @@
+{
+  "plugins": [
+    {
+      "id": "rivus-example-agents",
+      "module": "./rivus-agents.plugin.mjs",
+      "required": true
+    }
+  ],
+  "agents": [
+    {
+      "agentId": "langfuse-demo",
+      "endpointIds": ["langfuse-demo-feishu"],
+      "pluginId": "rivus-example-agents",
+      "profileId": "langfuse-demo",
+      "skills": { "allow": ["rivus-example-agents/langfuse-html-publisher"] },
+      "tools": {
+        "allow": ["rivus-example-agents/write-html-artifact", "rivus-example-agents/lark-drive-upload-html"]
+      }
+    }
+  ],
+  "endpoints": [
+    {
+      "id": "langfuse-demo-feishu",
+      "agentId": "langfuse-demo",
+      "sessionNamespace": "langfuse-demo-v1",
+      "credentialRef": "env:RIVUS_AGENT_A_FEISHU",
+      "enabled": true,
+      "required": true,
+      "baseUrl": "https://open.feishu.cn",
+      "streamMinIntervalMs": 200,
+      "progressDisplay": "collapsed",
+      "groupPolicy": "ignore-unmentioned"
+    }
+  ],
+  "defaultAgentId": "langfuse-demo",
+  "defaultEndpointId": "langfuse-demo-feishu"
+}

package/templates/rivus-starter.plugin.mjs

@@ -0,0 +1,47 @@
+import { readCurrentWeather } from "./current-weather.mjs";
+
+const TOOL_ID = "rivus-starter/current-weather";
+const RUNTIME_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+
+export default {
+  manifest: {
+    apiVersion: "1",
+    id: "rivus-starter",
+    version: "1.0.0"
+  },
+  register(registry) {
+    registry.registerTool({
+      createExecutor: () => ({ execute: readCurrentWeather }),
+      description:
+        "Read current conditions and today's forecast from Open-Meteo, using the configured default when location is omitted",
+      digest: "sha256:rivus-starter-current-weather-v1",
+      id: TOOL_ID,
+      idempotency: "none",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          location: {
+            description: "City or place name. Omit it when the user did not specify one.",
+            maxLength: 100,
+            minLength: 1,
+            type: "string"
+          }
+        },
+        type: "object"
+      },
+      risk: "observe",
+      version: "1.0.0"
+    });
+    registry.registerAgentProfile({
+      displayName: "Rivus Agent",
+      id: "agent-a",
+      memory: { scopes: ["agent-private"] },
+      model: {},
+      runtimeTools: { allow: RUNTIME_TOOLS },
+      skills: { allow: [] },
+      systemPrompt:
+        "You are a concise local assistant. For current or today's weather, call current-weather. If the user did not name a location, omit location and report the Tool's resolved place.",
+      tools: { allow: [TOOL_ID] }
+    });
+  }
+};

package/templates/rivus.config.json

@@ -0,0 +1,114 @@
+{
+  "plugins": [
+    {
+      "id": "rivus-example-agents",
+      "module": "./rivus-agents.plugin.mjs",
+      "required": true
+    }
+  ],
+  "agents": [
+    {
+      "agentId": "agent-a",
+      "endpointIds": ["feishu-agent-a"],
+      "memory": { "scopes": ["agent-private"], "tool": true },
+      "pluginId": "rivus-example-agents",
+      "profileId": "agent-a",
+      "skills": { "allow": [] },
+      "tools": {
+        "allow": [
+          "rivus-example-agents/runtime-info",
+          "rivus-example-agents/save-note",
+          "rivus-example-agents/current-weather",
+          "rivus-example-agents/a-share-market-briefing"
+        ]
+      }
+    },
+    {
+      "agentId": "agent-b",
+      "endpointIds": ["feishu-agent-b"],
+      "memory": { "scopes": ["agent-private"], "tool": true },
+      "pluginId": "rivus-example-agents",
+      "profileId": "agent-b",
+      "skills": { "allow": [] },
+      "tools": {
+        "allow": [
+          "rivus-example-agents/runtime-info",
+          "rivus-example-agents/save-note",
+          "rivus-example-agents/current-weather"
+        ]
+      }
+    }
+  ],
+  "automations": [
+    {
+      "id": "daily-ielts-word",
+      "agentId": "agent-a",
+      "templateId": "rivus-example-agents/daily-ielts-word",
+      "enabled": false,
+      "required": true,
+      "schedule": "0 10 * * *",
+      "timeZone": "Asia/Shanghai",
+      "delivery": {
+        "endpointId": "feishu-agent-a",
+        "targetRef": "env:RIVUS_DAILY_IELTS_WORD_TARGET",
+        "targetType": "union_id"
+      }
+    },
+    {
+      "id": "a-share-pre-market",
+      "agentId": "agent-a",
+      "templateId": "rivus-example-agents/a-share-pre-market",
+      "enabled": false,
+      "required": true,
+      "schedule": "0 9 * * 1-5",
+      "timeZone": "Asia/Shanghai",
+      "delivery": {
+        "endpointId": "feishu-agent-a",
+        "targetRef": "env:RIVUS_A_SHARE_BRIEFING_TARGET",
+        "targetType": "union_id"
+      }
+    },
+    {
+      "id": "a-share-post-market",
+      "agentId": "agent-a",
+      "templateId": "rivus-example-agents/a-share-post-market",
+      "enabled": false,
+      "required": true,
+      "schedule": "0 16 * * 1-5",
+      "timeZone": "Asia/Shanghai",
+      "delivery": {
+        "endpointId": "feishu-agent-a",
+        "targetRef": "env:RIVUS_A_SHARE_BRIEFING_TARGET",
+        "targetType": "union_id"
+      }
+    }
+  ],
+  "endpoints": [
+    {
+      "id": "feishu-agent-a",
+      "agentId": "agent-a",
+      "sessionNamespace": "feishu-agent-a-v1",
+      "credentialRef": "env:RIVUS_AGENT_A_FEISHU",
+      "enabled": true,
+      "required": true,
+      "baseUrl": "https://open.feishu.cn",
+      "streamMinIntervalMs": 200,
+      "progressDisplay": "collapsed",
+      "groupPolicy": "mention-only"
+    },
+    {
+      "id": "feishu-agent-b",
+      "agentId": "agent-b",
+      "sessionNamespace": "feishu-agent-b-v1",
+      "credentialRef": "env:RIVUS_AGENT_B_FEISHU",
+      "enabled": true,
+      "required": true,
+      "baseUrl": "https://open.feishu.cn",
+      "streamMinIntervalMs": 200,
+      "progressDisplay": "collapsed",
+      "groupPolicy": "mention-only"
+    }
+  ],
+  "defaultAgentId": "agent-a",
+  "defaultEndpointId": "feishu-agent-a"
+}