@rivus/agent 0.6.2 → 0.7.0

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

@@ -1,5 +1,5 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { join, relative } from "node:path";
 import { Effect } from "effect";
 import * as Lark from "@larksuiteoapi/node-sdk";
@@ -14,8 +14,13 @@ import {
   createAgentsMdInstructionsProvider,
   createAgentHarness,
   createAgentHarnessPooledRuntime,
+  createBackgroundSessionHostTools,
+  createBackgroundSessionService,
+  createBackgroundSessionStepSourceMessageId,
+  createBackgroundSessionSupervisor,
   createRivusMemoryToolDescriptor,
   createConfiguredFeishuAutomationCardSender,
+  createConfiguredFeishuBackgroundSessionDelivery,
   createConfiguredFeishuCardRolloverRuntime,
   createConfiguredFeishuHumanInteractionPresenter,
   createConfiguredFeishuOpenApiClient,
@@ -43,6 +48,10 @@ import {
   createToolBroker,
   createUuidRunIds,
   createWorkspaceRootHandle,
+  loadRivusDeploymentManifest,
+  openJsonlBackgroundSessionDeliveryStore,
+  openJsonlBackgroundSessionRepository,
+  resolveBackgroundSessionSupervisorIntervalMs,
   openJsonlFeishuCardDeliveryLedger,
   openJsonlFeishuInboxRepository,
   openJsonlAgentMemoryService,
@@ -53,13 +62,16 @@ import {
   resolveLangfuseTelemetryConfig,
   validateProjectSkillCatalog,
   validateProjectSkillCommand,
+  type CreateRivusDeploymentBackgroundSessionInput,
   type CreateRivusDeploymentEndpointInput,
   type CreateRivusDeploymentAutomationInput,
   type CreateRivusDeploymentRuntimeInput,
   type ConfiguredFeishuOpenApiResponse,
   type FeishuAgentRunPreparation,
+  type FeishuBackgroundSessionDelivery,
   type FeishuWebSocketClient,
   type RivusDaemonConfig,
+  type RivusDeploymentBackgroundSession,
   type RivusDeploymentBootstrapContext,
   type RivusThinkingLevel
 } from "@rivus/agent";
@@ -94,6 +106,144 @@ export async function createRivusDeploymentAdapters(context: RivusDeploymentBoot
       request: (input) => request(input).pipe(Effect.map((response) => response as ConfiguredFeishuOpenApiResponse))
     });
   const interactionRegistry = createHumanInteractionEndpointRegistry();
+  const manifest = await loadRivusDeploymentManifest(context.manifestPath);
+  const backgroundSessionsConfig = manifest.backgroundSessions;
+  const sessionRepository = backgroundSessionsConfig?.enabled
+    ? await openJsonlBackgroundSessionRepository({
+        filePath: join(STATE_DIR, "background-sessions", "sessions.jsonl")
+      })
+    : undefined;
+  const sessionDeliveries = backgroundSessionsConfig?.enabled
+    ? await openJsonlBackgroundSessionDeliveryStore({
+        filePath: join(STATE_DIR, "background-sessions", "deliveries.jsonl")
+      })
+    : undefined;
+  const deliveryClients = new Map<string, FeishuBackgroundSessionDelivery>();
+  const backgroundService = backgroundSessionsConfig?.enabled
+    ? createBackgroundSessionService({
+        clock: { now: () => new Date().toISOString() },
+        deliveries: sessionDeliveries!,
+        repository: sessionRepository!
+      })
+    : undefined;
+  const createBackgroundSessionAdapter = (
+    input: CreateRivusDeploymentBackgroundSessionInput
+  ): RivusDeploymentBackgroundSession => {
+    const resolveDeliverySender = async (endpointId: string): Promise<FeishuBackgroundSessionDelivery> => {
+      const existing = deliveryClients.get(endpointId);
+      if (existing) return existing;
+      const endpoint = manifest.endpoints.find(({ id }) => id === endpointId);
+      if (!endpoint) throw new Error(`background session delivery endpoint not found: ${endpointId}`);
+      const credentials = resolveFeishuEndpointCredentials(endpoint.credentialRef, context.env);
+      const config: RivusDaemonConfig = {
+        agentId: endpoint.agentId,
+        feishu: {
+          ...credentials,
+          baseUrl: endpoint.baseUrl,
+          cardStreamLeaseMs: endpoint.cardStreamLeaseMs,
+          streamMinIntervalMs: endpoint.streamMinIntervalMs
+        },
+        pi: {}
+      };
+      const sender = createConfiguredFeishuBackgroundSessionDelivery({
+        client: createOpenApiClient(config),
+        config
+      });
+      deliveryClients.set(endpointId, sender);
+      return sender;
+    };
+    const supervisor = createBackgroundSessionSupervisor({
+      clock: { now: () => new Date().toISOString() },
+      config: {
+        intervalMs: resolveBackgroundSessionSupervisorIntervalMs(input.config.leaseMs),
+        leaseMs: input.config.leaseMs,
+        leaseRenewalIntervalMs: input.config.leaseRenewalIntervalMs,
+        maxConcurrentSessions: input.config.maxConcurrentSessions,
+        maxConsecutiveFailures: input.config.maxConsecutiveFailures,
+        retryBackoffMs: input.config.retryBackoffMs,
+        sessionLifetimeMs: input.config.sessionLifetimeMs
+      },
+      deliveries: sessionDeliveries!,
+      deliver: async (delivery) => {
+        const session = await sessionRepository!.get(delivery.sessionId);
+        if (!session) throw new Error(`background session not found for delivery: ${delivery.sessionId}`);
+        if (!session.origin.conversationId) {
+          throw new Error(`background session has no delivery conversation: ${delivery.sessionId}`);
+        }
+        const sender = await resolveDeliverySender(session.origin.endpointId);
+        return sender.deliver({
+          chatId: session.origin.conversationId,
+          deliveryId: delivery.deliveryId,
+          displayName: session.displayName,
+          kind: delivery.kind,
+          sessionId: session.sessionId,
+          text: delivery.text
+        });
+      },
+      onError: (error) => {
+        console.error("Background session supervisor failed", error);
+      },
+      repository: sessionRepository!,
+      runStep: async ({ session, signal, wakeText }) => {
+        let runId: string | undefined;
+        const invocation = {
+          allowedActorOpenIds: session.origin.allowedActorOpenIds,
+          endpointId: session.origin.endpointId,
+          kind: "background-session" as const,
+          ...(session.origin.memory ? { memory: session.origin.memory } : {}),
+          sessionId: session.sessionId,
+          sourceMessageId: createBackgroundSessionStepSourceMessageId(session.sessionId, session.stepCount + 1),
+          tenantKey: session.origin.tenantKey
+        };
+        const abortPromise = new Promise<never>((_resolve, reject) => {
+          signal.addEventListener(
+            "abort",
+            () => {
+              if (runId) {
+                void input.cancel({
+                  agentId: session.authority.agentId,
+                  reason: "background session step aborted",
+                  runId,
+                  sessionKey: session.authority.sessionKey
+                });
+              }
+              reject(new Error("background session step aborted"));
+            },
+            { once: true }
+          );
+        });
+        const runPromise = input
+          .run({
+            agentId: session.authority.agentId,
+            invocation,
+            onUpdate: (update) => {
+              if (update.event.type === "agent_run_accepted" && !runId) {
+                runId = update.event.runId;
+              }
+            },
+            sessionKey: session.authority.sessionKey,
+            text: wakeText
+          })
+          .then((result) => readStepRunResult(result));
+        return Promise.race([runPromise, abortPromise]);
+      },
+      sleep
+    });
+    let running = false;
+    return {
+      running: () => running,
+      status: () => supervisor.status(),
+      start: async () => {
+        await Effect.runPromise(supervisor.recover());
+        await Effect.runPromise(supervisor.start());
+        running = true;
+      },
+      stop: async () => {
+        await Effect.runPromise(supervisor.stop());
+        running = false;
+      }
+    };
+  };
   return {
     dispose: () => telemetry?.shutdown(),
     createRecoveryControl: () =>
@@ -101,6 +251,9 @@ export async function createRivusDeploymentAdapters(context: RivusDeploymentBoot
         endpointsDirectory: join(STATE_DIR, "endpoints"),
         instancesDirectory: join(STATE_DIR, "instances")
       }),
+    createBackgroundSession: backgroundSessionsConfig?.enabled
+      ? (input: CreateRivusDeploymentBackgroundSessionInput) => createBackgroundSessionAdapter(input)
+      : undefined,
     createAutomation: async (input: CreateRivusDeploymentAutomationInput) => {
       const credentials = resolveFeishuEndpointCredentials(input.deliveryEndpoint.credentialRef, context.env);
       const config: RivusDaemonConfig = {
@@ -278,7 +431,18 @@ export async function createRivusDeploymentAdapters(context: RivusDeploymentBoot
       const broker = createToolBroker({
         approvals: createRoutedHumanInteractionToolApprovalService(interactionRegistry),
         catalog: input.catalog,
-        ...(input.definition.memory.tool ? { hostTools: [createRivusMemoryToolDescriptor({ memory })] } : {}),
+        hostTools: [
+          ...(input.definition.memory.tool ? [createRivusMemoryToolDescriptor({ memory })] : []),
+          ...(backgroundService
+            ? [
+                ...createBackgroundSessionHostTools({
+                  createSessionId: () => `bg-${randomUUID()}`,
+                  definition: input.definition,
+                  service: backgroundService
+                })
+              ]
+            : [])
+        ],
         operations: await openJsonlToolOperationLedger({ filePath: join(instanceState, "tool-operations.jsonl") }),
         policy: { current: async () => ({ epoch: 1, revokedToolIds: [] }) }
       });
@@ -374,10 +538,14 @@ export async function createRivusDeploymentAdapters(context: RivusDeploymentBoot
               eventSinks: telemetry ? [eventLog, telemetry.sink] : [eventLog],
               initialEvents: eventsForSession(initialEvents, sessionKey),
               loop,
-              runIds: createUuidRunIds()
+              runIds: createUuidRunIds(),
+              ...(input.binding.kind === "background-session" && backgroundSessionsConfig
+                ? { runTimeoutMs: backgroundSessionsConfig.stepTimeoutMs }
+                : {})
             })
           ),
-        maxConcurrentSessions: 4,
+        maxConcurrentSessions:
+          input.binding.kind === "background-session" ? (backgroundSessionsConfig?.maxConcurrentSessions ?? 4) : 4,
         maxQueuedRuns: 32
       });
       return {
@@ -439,6 +607,21 @@ function readAutomationRunResult(result: unknown): { readonly body: string; read
   throw new Error("Scheduled Automation Agent Run did not produce a runId and final text");
 }
 
+function readStepRunResult(result: unknown): { readonly finalText: string; readonly runId: string } {
+  if (
+    result !== null &&
+    typeof result === "object" &&
+    "finalText" in result &&
+    typeof result.finalText === "string" &&
+    "runId" in result &&
+    typeof result.runId === "string" &&
+    result.runId.trim() !== ""
+  ) {
+    return { finalText: result.finalText, runId: result.runId };
+  }
+  throw new Error("Background session Agent Run did not produce a runId and final text");
+}
+
 function createLazyFeishuWebSocketClient(
   credentials: {
     readonly appId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivus/agent",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "A local agent daemon core built around a usable agent harness and domain events.",
   "type": "module",
   "license": "MIT",