@rivus/agent 0.1.0

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

@@ -0,0 +1,542 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { Effect } from "effect";
+import * as Lark from "@larksuiteoapi/node-sdk";
+import {
+  AuthStorage,
+  createAgentSession,
+  DefaultResourceLoader,
+  ModelRegistry,
+  SessionManager
+} from "@earendil-works/pi-coding-agent";
+import {
+  createAgentsMdInstructionsProvider,
+  createAgentHarness,
+  createAgentHarnessPooledRuntime,
+  createRivusMemoryToolDescriptor,
+  createConfiguredFeishuMarkdownMessageSender,
+  createConfiguredFeishuCardKitPublisher,
+  createConfiguredFeishuCardKitTargetPreparation,
+  createConfiguredFeishuHumanInteractionPresenter,
+  createConfiguredFeishuOpenApiClient,
+  createConfiguredFeishuTextReplySender,
+  createFeishuCotPublisher,
+  createFeishuDeploymentEndpoint,
+  createFeishuPresentationPreparation,
+  createFeishuCardDeliveryReconciler,
+  createHumanInteractionEndpointRegistry,
+  createHumanInteractionService,
+  createHumanInteractionToolApprovalGateway,
+  createJsonFetchRequest,
+  createJsonFileFeishuCardTargetRegistry,
+  createJsonlAgentEventLog,
+  createJsonlHumanInteractionRepository,
+  createLangfuseAgentTelemetry,
+  createLazyFeishuWebSocketEventDispatcher,
+  createPiAgentLoop,
+  createPiSkillRuntime,
+  createPiToolNameResolver,
+  createPiToolProxyDefinitions,
+  createPiSessionRegistry,
+  createRoutedHumanInteractionToolApprovalService,
+  createSessionScheduler,
+  createScheduledAutomation,
+  createSystemClock,
+  createToolBroker,
+  createUuidRunIds,
+  createWorkspaceRootHandle,
+  openJsonlFeishuCardDeliveryLedger,
+  openJsonlFeishuInboxRepository,
+  openJsonlAgentMemoryService,
+  openJsonAutomationTickRepository,
+  openJsonlToolOperationLedger,
+  openJsonlRecoveryControl,
+  resolveFeishuEndpointCredentials,
+  resolveLangfuseTelemetryConfig,
+  type CreateRivusDeploymentEndpointInput,
+  type CreateRivusDeploymentAutomationInput,
+  type CreateRivusDeploymentRuntimeInput,
+  type ConfiguredFeishuOpenApiResponse,
+  type FeishuWebSocketClient,
+  type RivusDaemonConfig,
+  type RivusDeploymentBootstrapContext,
+  type RivusThinkingLevel
+} from "@rivus/agent";
+
+type PiSessionOptions = NonNullable<Parameters<typeof createAgentSession>[0]>;
+
+const STATE_DIR = process.env.RIVUS_DEPLOYMENT_STATE_DIR?.trim() || ".rivus/deployment";
+const PI_AGENT_DIR = join(STATE_DIR, "pi-agent");
+const PI_AUTH_FILE = join(STATE_DIR, "pi-auth.json");
+const PI_MODELS_FILE = join(STATE_DIR, "pi-models.json");
+const THINKING_LEVELS = new Set<RivusThinkingLevel>(["off", "minimal", "low", "medium", "high", "xhigh"]);
+
+export async function createRivusDeploymentAdapters(context: RivusDeploymentBootstrapContext) {
+  await mkdir(PI_AGENT_DIR, { recursive: true });
+  const piOptions = await createPiSessionOptions(context);
+  const telemetryConfig = resolveLangfuseTelemetryConfig(context.env);
+  const telemetry = telemetryConfig ? createLangfuseAgentTelemetry(telemetryConfig) : undefined;
+  const memory = await openJsonlAgentMemoryService({
+    filePath: join(STATE_DIR, "memory", "agent-memory.jsonl")
+  });
+  const memoryTenantId = context.env.RIVUS_MEMORY_TENANT_ID?.trim() || "local";
+  const request = createJsonFetchRequest();
+  const createOpenApiClient = (config: RivusDaemonConfig) =>
+    createConfiguredFeishuOpenApiClient({
+      config,
+      request: (input) => request(input).pipe(Effect.map((response) => response as ConfiguredFeishuOpenApiResponse))
+    });
+  const interactionRegistry = createHumanInteractionEndpointRegistry();
+  const workspaceInstructions = await createAgentsMdInstructionsProvider().resolve({
+    maxBytes: 64 * 1024,
+    workingDirectory: ".",
+    workspaceRoot: await createWorkspaceRootHandle(process.cwd())
+  });
+
+  return {
+    dispose: () => telemetry?.shutdown(),
+    createRecoveryControl: () =>
+      openJsonlRecoveryControl({
+        endpointsDirectory: join(STATE_DIR, "endpoints"),
+        instancesDirectory: join(STATE_DIR, "instances")
+      }),
+    createAutomation: async (input: CreateRivusDeploymentAutomationInput) => {
+      const credentials = resolveFeishuEndpointCredentials(input.deliveryEndpoint.credentialRef, context.env);
+      const config: RivusDaemonConfig = {
+        agentId: input.definition.agentId,
+        feishu: {
+          ...credentials,
+          baseUrl: input.deliveryEndpoint.baseUrl,
+          streamMinIntervalMs: input.deliveryEndpoint.streamMinIntervalMs
+        },
+        pi: {}
+      };
+      const openApiClient = createOpenApiClient(config);
+      const sender = createConfiguredFeishuMarkdownMessageSender({
+        client: openApiClient,
+        config
+      });
+      const repository = await openJsonAutomationTickRepository({
+        filePath: join(
+          STATE_DIR,
+          "automations",
+          createHash("sha256").update(input.automationId).digest("hex").slice(0, 16),
+          "ticks.json"
+        )
+      });
+      const target = resolveAutomationTarget(input.definition.delivery.targetRef, context.env);
+      const automation = createScheduledAutomation({
+        automationId: input.automationId,
+        binding: {
+          agentId: input.definition.agentId,
+          bindingId: input.automationId,
+          delivery: {
+            endpointId: input.definition.delivery.endpointId,
+            targetKey: createHash("sha256").update(target).digest("hex"),
+            targetType: input.definition.delivery.targetType
+          },
+          schedule: input.definition.schedule,
+          servicePrincipalId: `automation:${input.automationId}`,
+          skillGrantRevision: input.definition.runtimeDefinition.skillGrantSet.revision,
+          skillIds: input.definition.template.requestedSkillIds,
+          templateId: input.definition.templateId,
+          timeZone: input.definition.timeZone,
+          toolIds: input.definition.template.requestedToolIds
+        },
+        createInput: input.definition.template.createInput,
+        deliver: ({ body, idempotencyKey }) =>
+          Effect.runPromise(
+            sender.send({
+              idempotencyKey,
+              receiveId: target,
+              receiveIdType: input.definition.delivery.targetType,
+              markdown: body
+            })
+          ),
+        onError: () => {
+          console.error(`Scheduled Automation ${input.automationId} failed; it will retry`);
+        },
+        repository,
+        run: async (runInput) => readAutomationRunResult(await input.run(runInput))
+      });
+      return automation;
+    },
+    createEndpoint: async (input: CreateRivusDeploymentEndpointInput) => {
+      const credentials = resolveFeishuEndpointCredentials(input.definition.credentialRef, context.env);
+      const botOpenId = await resolveFeishuBotOpenId(credentials, input.definition.baseUrl);
+      const endpointState = join(STATE_DIR, "endpoints", input.endpointId);
+      const cardTargets = createJsonFileFeishuCardTargetRegistry({
+        filePath: join(endpointState, "feishu-card-targets.json")
+      });
+      const cardLedger = await openJsonlFeishuCardDeliveryLedger({
+        filePath: join(endpointState, "feishu-card-delivery.jsonl")
+      });
+      const inbox = await openJsonlFeishuInboxRepository({ filePath: join(endpointState, "feishu-inbox.jsonl") });
+      const config: RivusDaemonConfig = {
+        agentId: input.agentId,
+        feishu: {
+          ...credentials,
+          baseUrl: input.definition.baseUrl,
+          streamMinIntervalMs: input.definition.streamMinIntervalMs
+        },
+        pi: {}
+      };
+      const openApiClient = createOpenApiClient(config);
+      const cotPublisher = input.definition.experimental?.cotMessages
+        ? createFeishuCotPublisher({
+            baseUrl: resolveExperimentalCotBaseUrl(context.env),
+            client: openApiClient,
+            minIntervalMs: input.definition.streamMinIntervalMs
+          })
+        : undefined;
+      const interactions = createHumanInteractionService({
+        clock: { now: () => new Date().toISOString() },
+        presenter: createConfiguredFeishuHumanInteractionPresenter({
+          client: openApiClient,
+          config
+        }),
+        repository: createJsonlHumanInteractionRepository({
+          filePath: join(endpointState, "human-interactions.jsonl")
+        })
+      });
+      const publisher = createConfiguredFeishuCardKitPublisher({
+        agentName: input.agentId,
+        client: openApiClient,
+        config,
+        ledger: cardLedger,
+        resolveTarget: (runId) => cardTargets.resolveTarget(runId),
+        sleep
+      });
+      const endpointEvents = createJsonlAgentEventLog({
+        filePath: join(STATE_DIR, "instances", input.instanceId, "agent-events.jsonl")
+      });
+      await Effect.runPromise(
+        createFeishuCardDeliveryReconciler({
+          events: await Effect.runPromise(endpointEvents.readAll()),
+          ledger: cardLedger,
+          publish: (action) => publisher.publish(action)
+        }).reconcile()
+      );
+      const replies = createConfiguredFeishuTextReplySender({
+        client: openApiClient,
+        config
+      });
+      const prepareCardTarget = createConfiguredFeishuCardKitTargetPreparation({
+        client: openApiClient,
+        config,
+        registry: cardTargets,
+        title: input.agentId
+      });
+      const endpoint = createFeishuDeploymentEndpoint({
+        agentId: input.agentId,
+        botOpenId,
+        cancel: input.cancel,
+        endpointId: input.endpointId,
+        eventDispatcher: createLazyFeishuWebSocketEventDispatcher(() => new Lark.EventDispatcher({})),
+        groupPolicy: input.definition.groupPolicy,
+        handle: input.handle,
+        inboxRepository: inbox,
+        interactions,
+        maxPendingMessages: 100,
+        memoryTenantId,
+        onCapacityExceeded: (payload) =>
+          replies.reply(payload.event.message.message_id, "Rivus is busy. Please retry in a moment."),
+        prepareRun: createFeishuPresentationPreparation({
+          ...(cotPublisher ? { cotPublisher } : {}),
+          prepareCardTarget,
+          reportCotError: (operation, error) => reportCotError(input.endpointId, operation, error)
+        }),
+        publish: (action) => publisher.publish(action),
+        ...(cotPublisher
+          ? {
+              publishRunUpdate: (update) =>
+                cotPublisher
+                  .publish(update)
+                  .pipe(Effect.catchAll((error) => reportCotError(input.endpointId, "update", error)))
+            }
+          : {}),
+        sessionNamespace: input.definition.sessionNamespace,
+        sleep,
+        websocketClient: createLazyFeishuWebSocketClient(credentials, input.definition.baseUrl),
+        workerConcurrency: 4
+      });
+      interactionRegistry.register(input.endpointId, interactions);
+      return endpoint;
+    },
+    createRuntime: async (input: CreateRivusDeploymentRuntimeInput) => {
+      const instanceState = join(STATE_DIR, "instances", input.instanceId);
+      await mkdir(instanceState, { recursive: true });
+      const eventLog = createJsonlAgentEventLog({ filePath: join(instanceState, "agent-events.jsonl") });
+      const initialEvents = await Effect.runPromise(eventLog.readAll());
+      const broker = createToolBroker({
+        approvals: createRoutedHumanInteractionToolApprovalService(interactionRegistry),
+        catalog: input.catalog,
+        ...(input.definition.memory.tool ? { hostTools: [createRivusMemoryToolDescriptor({ memory })] } : {}),
+        operations: await openJsonlToolOperationLedger({ filePath: join(instanceState, "tool-operations.jsonl") }),
+        policy: { current: async () => ({ epoch: 1, revokedToolIds: [] }) }
+      });
+      const resolveToolName = createPiToolNameResolver(input.definition.tools);
+      const skillRuntime = createPiSkillRuntime(input.definition.skills);
+      const sessionRegistry = createPiSessionRegistry({
+        createSession: async (firstInput) => {
+          let activeInput = firstInput;
+          const customTools = [
+            ...createPiToolProxyDefinitions({
+              agentId: input.agentId,
+              approvals: createHumanInteractionToolApprovalGateway({ registry: interactionRegistry }),
+              broker,
+              getActiveInput: () => activeInput,
+              instanceId: input.instanceId,
+              memoryScopes: input.definition.memory.scopes,
+              toolGrantSet: input.definition.toolGrantSet,
+              tools: input.definition.tools
+            }),
+            ...(skillRuntime.tool ? [skillRuntime.tool] : [])
+          ];
+          const resourceLoader = new DefaultResourceLoader({
+            agentDir: PI_AGENT_DIR,
+            appendSystemPromptOverride: () =>
+              [workspaceInstructions.content, skillRuntime.prompt].filter((content) => content.length > 0),
+            cwd: process.cwd(),
+            noContextFiles: true,
+            noExtensions: true,
+            noPromptTemplates: true,
+            noSkills: true,
+            noThemes: true,
+            systemPromptOverride: () => input.definition.systemPrompt
+          });
+          await resourceLoader.reload();
+          const result = await createAgentSession({
+            ...piOptions,
+            customTools,
+            resourceLoader,
+            sessionManager: SessionManager.create(process.cwd(), join(instanceState, "sessions")),
+            tools: customTools.map(({ name }) => name)
+          });
+          return {
+            activate: (loopInput) => {
+              activeInput = loopInput;
+            },
+            dispose: () => result.session.dispose(),
+            resolveToolName,
+            session: result.session
+          };
+        }
+      });
+      const loop = createPiAgentLoop({
+        disposeSessionAfterRun: false,
+        ...(telemetry ? { modelContentObserver: telemetry.modelContentObserver } : {}),
+        resolveSession: (loopInput) => sessionRegistry.resolve(loopInput)
+      });
+      const scheduler = createSessionScheduler({
+        createRuntime: (sessionKey) =>
+          createAgentHarnessPooledRuntime(
+            createAgentHarness({
+              clock: createSystemClock(),
+              eventSinks: telemetry ? [eventLog, telemetry.sink] : [eventLog],
+              initialEvents: eventsForSession(initialEvents, sessionKey),
+              loop,
+              runIds: createUuidRunIds()
+            })
+          ),
+        maxConcurrentSessions: 4,
+        maxQueuedRuns: 32
+      });
+      return {
+        ...scheduler,
+        dispose: async () => {
+          await scheduler.dispose?.();
+          await sessionRegistry.disposeAll();
+        }
+      };
+    }
+  };
+}
+
+function eventsForSession<T extends { readonly runId: string; readonly sessionKey?: string }>(
+  events: ReadonlyArray<T>,
+  sessionKey: string
+): ReadonlyArray<T> {
+  const runIds = new Set(events.filter((event) => event.sessionKey === sessionKey).map((event) => event.runId));
+  return events.filter((event) => runIds.has(event.runId));
+}
+
+function resolveAutomationTarget(targetRef: string, env: Readonly<Record<string, string | undefined>>): string {
+  if (!targetRef.startsWith("env:")) throw new Error("Automation delivery targetRef must use env:<VARIABLE>");
+  const variable = targetRef.slice("env:".length);
+  if (!/^[A-Z][A-Z0-9_]*$/.test(variable)) throw new Error(`Invalid Automation delivery targetRef: ${targetRef}`);
+  const target = env[variable]?.trim();
+  if (!target) throw new Error(`${variable} is required`);
+  return target;
+}
+
+function resolveExperimentalCotBaseUrl(env: Readonly<Record<string, string | undefined>>): string {
+  const baseUrl = env.RIVUS_FEISHU_COT_BASE_URL?.trim();
+  if (!baseUrl) {
+    throw new Error("RIVUS_FEISHU_COT_BASE_URL is required when experimental.cotMessages is enabled");
+  }
+  return baseUrl;
+}
+
+function reportCotError(endpointId: string, operation: string, error: unknown): Effect.Effect<void> {
+  return Effect.sync(() => {
+    const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    console.error(`Experimental Feishu COT ${operation} failed for endpoint ${endpointId}: ${detail}`);
+  });
+}
+
+function readAutomationRunResult(result: unknown): { readonly body: string; readonly runId: string } {
+  if (
+    result !== null &&
+    typeof result === "object" &&
+    "finalText" in result &&
+    typeof result.finalText === "string" &&
+    result.finalText.trim() !== "" &&
+    "runId" in result &&
+    typeof result.runId === "string" &&
+    result.runId.trim() !== ""
+  ) {
+    return { body: result.finalText, runId: result.runId };
+  }
+  throw new Error("Scheduled Automation Agent Run did not produce a runId and final text");
+}
+
+function createLazyFeishuWebSocketClient(
+  credentials: {
+    readonly appId: string;
+    readonly appSecret: string;
+  },
+  domain: string
+): FeishuWebSocketClient {
+  let client: Lark.WSClient | undefined;
+  let connected = false;
+  return {
+    connected: () => connected,
+    close: () => {
+      client?.close();
+      client = undefined;
+      connected = false;
+    },
+    start: (options) =>
+      new Promise<void>((resolve, reject) => {
+        let settled = false;
+        const settle = (callback: () => void) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeout);
+          callback();
+        };
+        const timeout = setTimeout(
+          () => settle(() => reject(new Error("Feishu WebSocket handshake timed out after 15000ms"))),
+          15_000
+        );
+        client ??= new Lark.WSClient({
+          ...credentials,
+          domain,
+          handshakeTimeoutMs: 10_000,
+          onError: (error) => {
+            connected = false;
+            settle(() => reject(error));
+          },
+          onReady: () => {
+            connected = true;
+            settle(resolve);
+          },
+          onReconnected: () => {
+            connected = true;
+          },
+          onReconnecting: () => {
+            connected = false;
+          }
+        });
+        void client.start(options as Parameters<Lark.WSClient["start"]>[0]).catch((error: unknown) => {
+          connected = false;
+          settle(() => reject(error));
+        });
+      })
+  };
+}
+
+async function resolveFeishuBotOpenId(
+  credentials: {
+    readonly appId: string;
+    readonly appSecret: string;
+  },
+  domain: string
+): Promise<string> {
+  const response = (await new Lark.Client({ ...credentials, domain }).request({
+    method: "GET",
+    url: "/open-apis/bot/v3/info"
+  })) as { readonly bot?: { readonly open_id?: string }; readonly code?: number; readonly msg?: string };
+  const openId = response.bot?.open_id;
+  if (response.code !== 0 || !openId) {
+    throw new Error(`Feishu bot identity lookup failed: ${response.msg ?? "response missing bot.open_id"}`);
+  }
+  return openId;
+}
+
+async function createPiSessionOptions(context: RivusDeploymentBootstrapContext): Promise<PiSessionOptions> {
+  const authStorage = AuthStorage.create(PI_AUTH_FILE);
+  const modelReference = optional(context.env.PI_MODEL);
+  const configuredModel = modelReference ? parseModelReference(modelReference) : undefined;
+  const provider = configuredModel?.provider;
+  const apiKey = await resolvePiApiKey(context.env);
+  const baseUrl = optional(context.env.PI_BASE_URL);
+  if ((apiKey || baseUrl) && !provider) {
+    throw new Error("PI_API_KEY and PI_BASE_URL require PI_MODEL in provider/model form");
+  }
+  if (apiKey) authStorage.setRuntimeApiKey(provider!, apiKey);
+  if (baseUrl) await writeProviderBaseUrlOverride(provider!, baseUrl);
+  const modelRegistry = ModelRegistry.create(authStorage, baseUrl ? PI_MODELS_FILE : undefined);
+  const model = configuredModel ? modelRegistry.find(configuredModel.provider, configuredModel.modelId) : undefined;
+  if (modelReference && !model) throw new Error(`PI_MODEL ${modelReference} was not found in the Pi model registry`);
+  const thinkingLevel = readThinkingLevel(context.env.PI_THINKING_LEVEL);
+  return {
+    authStorage,
+    cwd: process.cwd(),
+    modelRegistry,
+    ...(model ? { model } : {}),
+    ...(thinkingLevel ? { thinkingLevel } : {})
+  };
+}
+
+async function resolvePiApiKey(env: Readonly<Record<string, string | undefined>>): Promise<string | undefined> {
+  const inline = optional(env.PI_API_KEY);
+  const filePath = optional(env.PI_API_KEY_FILE);
+  if (inline && filePath) throw new Error("PI_API_KEY and PI_API_KEY_FILE cannot both be set");
+  if (inline) return inline;
+  if (!filePath) return undefined;
+  const contents = optional(await readFile(filePath, "utf8"));
+  if (!contents) throw new Error("PI_API_KEY_FILE must not be empty");
+  return contents;
+}
+
+function optional(value: string | undefined): string | undefined {
+  return value?.trim() || undefined;
+}
+
+function parseModelReference(reference: string): { readonly modelId: string; readonly provider: string } {
+  const separator = reference.indexOf("/");
+  if (separator <= 0 || separator === reference.length - 1) {
+    throw new Error("PI_MODEL must use provider/model form, for example zai/glm-5.1");
+  }
+  return { modelId: reference.slice(separator + 1), provider: reference.slice(0, separator) };
+}
+
+function readThinkingLevel(value: string | undefined): RivusThinkingLevel | undefined {
+  const level = optional(value);
+  if (!level) return undefined;
+  if (!THINKING_LEVELS.has(level as RivusThinkingLevel)) {
+    throw new Error("PI_THINKING_LEVEL must be one of off, minimal, low, medium, high, xhigh");
+  }
+  return level as RivusThinkingLevel;
+}
+
+function sleep(ms: number): Effect.Effect<void> {
+  return Effect.promise(() => new Promise((resolve) => setTimeout(resolve, ms)));
+}
+
+async function writeProviderBaseUrlOverride(provider: string, baseUrl: string): Promise<void> {
+  await writeFile(PI_MODELS_FILE, `${JSON.stringify({ providers: { [provider]: { baseUrl } } }, null, 2)}\n`, "utf8");
+}