@rivus/agent 0.1.0

package/examples/pi-feishu.bootstrap.ts

@@ -0,0 +1,225 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { Effect } from "effect";
+import * as Lark from "@larksuiteoapi/node-sdk";
+import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@earendil-works/pi-coding-agent";
+import {
+  createJsonFetchRequest,
+  createJsonFileFeishuCardTargetRegistry,
+  createJsonlAgentEventLog,
+  createLazyFeishuWebSocketEventDispatcher,
+  createRivusDaemonStatusHttpServer,
+  createPiAgentLoop,
+  createPiSessionRegistry,
+  createSystemClock,
+  createUuidRunIds,
+  restoreConfiguredRivusDaemonBootstrap,
+  type ConfiguredRivusDaemonBootstrapRequest,
+  type ConfiguredRivusDaemonBootstrapResponse,
+  type FeishuWebSocketClient,
+  type RivusDaemonBootstrapContext,
+  type RivusDaemonFeishuReplayRunner,
+  type RivusDaemonProcess,
+  type RivusDaemonPromptRunner,
+  type RivusDaemonStatusReporter,
+  type FeishuReceiveMessagePayload,
+  type FeishuReceiveMessageReplayOptions
+} from "@rivus/agent";
+
+type PiSessionOptions = NonNullable<Parameters<typeof createAgentSession>[0]>;
+
+const STATE_DIR = "./.rivus";
+const CARD_TARGETS_FILE = `${STATE_DIR}/feishu-card-targets.json`;
+const EVENT_LOG_FILE = `${STATE_DIR}/agent-events.jsonl`;
+const PI_AUTH_FILE = `${STATE_DIR}/pi-auth.json`;
+const PI_MODELS_FILE = `${STATE_DIR}/pi-models.json`;
+
+export async function createRivusDaemonProcess(
+  context: RivusDaemonBootstrapContext
+): Promise<RivusDaemonProcess & RivusDaemonPromptRunner & RivusDaemonStatusReporter & RivusDaemonFeishuReplayRunner> {
+  await mkdir(STATE_DIR, { recursive: true });
+
+  const piSessionOptions = await createPiSessionOptions(context);
+  const sessionRegistry = createPiSessionRegistry({
+    createSession: async () => {
+      const result = await createAgentSession({
+        ...piSessionOptions,
+        sessionManager: SessionManager.create(process.cwd())
+      });
+      return {
+        dispose: () => result.session.dispose(),
+        session: result.session
+      };
+    }
+  });
+  const piLoop = createPiAgentLoop({
+    disposeSessionAfterRun: false,
+    resolveSession: (input) => sessionRegistry.resolve(input)
+  });
+  const statusPort = readOptionalPort(context.env.RIVUS_STATUS_PORT);
+  const request = createJsonFetchRequest();
+
+  const bootstrap = await Effect.runPromise(
+    restoreConfiguredRivusDaemonBootstrap({
+      cardTargets: createJsonFileFeishuCardTargetRegistry({
+        filePath: CARD_TARGETS_FILE
+      }),
+      clock: createSystemClock(),
+      config: context.config,
+      ...(statusPort === undefined
+        ? {}
+        : {
+            createStatusTransport: (statusReporter: RivusDaemonStatusReporter) =>
+              createRivusDaemonStatusHttpServer({
+                port: statusPort,
+                statusReporter
+              })
+          }),
+      eventDispatcher: createLazyFeishuWebSocketEventDispatcher(() => new Lark.EventDispatcher({})),
+      eventLog: createJsonlAgentEventLog({
+        filePath: EVENT_LOG_FILE
+      }),
+      loop: piLoop,
+      request: (input: ConfiguredRivusDaemonBootstrapRequest) =>
+        request(input).pipe(Effect.map((response) => response as ConfiguredRivusDaemonBootstrapResponse)),
+      runIds: createUuidRunIds(),
+      sleep: (ms) => Effect.promise(() => new Promise<void>((resolve) => setTimeout(resolve, ms))),
+      websocketClient: createLazyFeishuWebSocketClient({
+        appId: context.config.feishu.appId,
+        appSecret: context.config.feishu.appSecret
+      })
+    })
+  );
+
+  return {
+    promptText: (command) => bootstrap.promptText(command),
+    replayReceiveMessage: (payload: FeishuReceiveMessagePayload, options?: FeishuReceiveMessageReplayOptions) =>
+      bootstrap.runtime.replayReceiveMessage(payload, options),
+    running: () => bootstrap.process.running(),
+    start: () => bootstrap.process.start(),
+    status: () => bootstrap.status(),
+    stop: () =>
+      Effect.gen(function* () {
+        yield* bootstrap.process.stop();
+        yield* Effect.tryPromise({
+          try: () => sessionRegistry.disposeAll(),
+          catch: (error) => error
+        });
+      })
+  };
+}
+
+function createLazyFeishuWebSocketClient(options: {
+  readonly appId: string;
+  readonly appSecret: string;
+}): FeishuWebSocketClient {
+  let client:
+    | {
+        close(): void;
+        start(options: Parameters<FeishuWebSocketClient["start"]>[0]): Promise<void> | void;
+      }
+    | undefined;
+
+  return {
+    start: (startOptions) => {
+      client ??= new Lark.WSClient({
+        appId: options.appId,
+        appSecret: options.appSecret
+      });
+      return client.start(startOptions);
+    },
+    close: () => {
+      client?.close();
+      client = undefined;
+    }
+  };
+}
+
+async function createPiSessionOptions(context: RivusDaemonBootstrapContext): Promise<PiSessionOptions> {
+  const authStorage = AuthStorage.create(PI_AUTH_FILE);
+  const provider = readProviderFromModel(context.config.pi.model);
+
+  if (context.config.pi.apiKey) {
+    if (!provider) {
+      throw new Error("PI_API_KEY requires PI_MODEL in provider/model form, for example zai/glm-5.1");
+    }
+    authStorage.setRuntimeApiKey(provider, context.config.pi.apiKey);
+  }
+
+  if (context.config.pi.baseUrl) {
+    if (!provider) {
+      throw new Error("PI_BASE_URL requires PI_MODEL in provider/model form, for example zai/glm-5.1");
+    }
+    await writeProviderBaseUrlOverride(provider, context.config.pi.baseUrl);
+  }
+
+  const modelRegistry = ModelRegistry.create(authStorage, context.config.pi.baseUrl ? PI_MODELS_FILE : undefined);
+  const model = context.config.pi.model ? resolveConfiguredPiModel(modelRegistry, context.config.pi.model) : undefined;
+  return {
+    authStorage,
+    cwd: process.cwd(),
+    modelRegistry,
+    ...(model ? { model } : {}),
+    ...(context.config.pi.thinkingLevel ? { thinkingLevel: context.config.pi.thinkingLevel } : {})
+  };
+}
+
+function resolveConfiguredPiModel(modelRegistry: ModelRegistry, modelReference: string): PiSessionOptions["model"] {
+  const provider = readProviderFromModel(modelReference);
+  const modelId = readModelIdFromModel(modelReference);
+  if (!provider || !modelId) {
+    throw new Error("PI_MODEL must use provider/model form, for example zai/glm-5.1");
+  }
+
+  const model = modelRegistry.find(provider, modelId);
+  if (!model) {
+    throw new Error(`PI_MODEL ${modelReference} was not found in the Pi model registry`);
+  }
+  return model as PiSessionOptions["model"];
+}
+
+function readProviderFromModel(model: string | undefined): string | undefined {
+  const slashIndex = model?.indexOf("/") ?? -1;
+  if (!model || slashIndex <= 0) {
+    return undefined;
+  }
+  return model.slice(0, slashIndex);
+}
+
+function readModelIdFromModel(model: string | undefined): string | undefined {
+  const slashIndex = model?.indexOf("/") ?? -1;
+  if (!model || slashIndex < 0 || slashIndex === model.length - 1) {
+    return undefined;
+  }
+  return model.slice(slashIndex + 1);
+}
+
+function readOptionalPort(value: string | undefined): number | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const port = Number(trimmed);
+  if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+    throw new Error("RIVUS_STATUS_PORT must be an integer between 0 and 65535");
+  }
+  return port;
+}
+
+async function writeProviderBaseUrlOverride(provider: string, baseUrl: string): Promise<void> {
+  await writeFile(
+    PI_MODELS_FILE,
+    `${JSON.stringify(
+      {
+        providers: {
+          [provider]: {
+            baseUrl
+          }
+        }
+      },
+      null,
+      2
+    )}\n`,
+    "utf8"
+  );
+}

package/examples/rivus-agents.plugin.mjs

@@ -0,0 +1,238 @@
+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 { createHtmlArtifactWriter, createLarkDriveHtmlUploader } from "./html-drive-tools.mjs";
+
+const TOOL_IDS = {
+  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 ALLOWED_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 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: () => 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: ALLOWED_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: ALLOWED_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: []
+    });
+  }
+};
+
+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/examples/rivus-langfuse-demo.config.json

@@ -0,0 +1,36 @@
+{
+  "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,
+      "groupPolicy": "ignore-unmentioned"
+    }
+  ],
+  "defaultAgentId": "langfuse-demo",
+  "defaultEndpointId": "langfuse-demo-feishu"
+}

package/examples/rivus.config.json

@@ -0,0 +1,83 @@
+{
+  "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"
+        ]
+      }
+    },
+    {
+      "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"
+      }
+    }
+  ],
+  "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,
+      "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,
+      "groupPolicy": "mention-only"
+    }
+  ],
+  "defaultAgentId": "agent-a",
+  "defaultEndpointId": "feishu-agent-a"
+}