@rivus/agent 0.6.1 → 0.7.0

package/dist/rivus-plugin-registry.js

@@ -1,5 +1,227 @@
 import { c as InvalidRivusPlugin, o as createRivusMemoryToolContract, r as RIVUS_MEMORY_TOOL_PLUGIN_ID, t as MEMORY_SCOPES } from "./agent-memory.js";
 import { createHash } from "node:crypto";
+//#region src/application/background-session/background-session-authority.ts
+const BACKGROUND_SESSION_TOOL_IDS = [
+	"background.start",
+	"background.wait",
+	"background.list",
+	"background.status",
+	"background.send",
+	"background.stop"
+];
+const BACKGROUND_SESSION_START_TOOL_ID = "background.start";
+const BACKGROUND_SESSION_TOOL_PLUGIN_ID = "rivus-core";
+const BACKGROUND_SESSION_TOOL_VERSION = "1.0.0";
+const BACKGROUND_SESSION_SESSION_KEY_PREFIX = "background";
+function createBackgroundSessionKey(sessionId) {
+	return `${BACKGROUND_SESSION_SESSION_KEY_PREFIX}:${sessionId}`;
+}
+function createBackgroundSessionStepSourceMessageId(sessionId, stepCount) {
+	return `bg:${sessionId}:step:${stepCount}`;
+}
+function createBackgroundSessionToolContracts() {
+	return [
+		Object.freeze({
+			description: "Start a background agent session. Use when the request must wait for external changes, observe over time, or continue working after the foreground run ends. Returns a stable session id immediately; the foreground response can finish here. The detached session continues with the granted Skills, CLI, Tools, Project Space, and Memory of this agent.",
+			digest: contractDigest("background.start"),
+			id: "background.start",
+			idempotency: "supported",
+			inputSchema: Object.freeze({
+				additionalProperties: false,
+				properties: Object.freeze({
+					displayName: {
+						type: "string",
+						maxLength: 200
+					},
+					prompt: {
+						type: "string",
+						minLength: 1,
+						maxLength: 2e4
+					}
+				}),
+				required: ["prompt"],
+				type: "object"
+			}),
+			pluginId: BACKGROUND_SESSION_TOOL_PLUGIN_ID,
+			risk: "mutate",
+			version: BACKGROUND_SESSION_TOOL_VERSION
+		}),
+		Object.freeze({
+			description: "Pause the current background session durably and end the current step. Call with delayMs to resume after a delay, with until to resume at an absolute ISO time, or with neither to wait for user input. After this call no further tool calls are accepted in this step.",
+			digest: contractDigest("background.wait"),
+			id: "background.wait",
+			idempotency: "supported",
+			inputSchema: Object.freeze({
+				additionalProperties: false,
+				properties: Object.freeze({
+					delayMs: {
+						type: "integer",
+						minimum: 1e3,
+						maximum: 864e5
+					},
+					reason: {
+						type: "string",
+						maxLength: 500
+					},
+					until: {
+						type: "string",
+						maxLength: 64
+					}
+				}),
+				type: "object"
+			}),
+			pluginId: BACKGROUND_SESSION_TOOL_PLUGIN_ID,
+			risk: "mutate",
+			version: BACKGROUND_SESSION_TOOL_VERSION
+		}),
+		Object.freeze({
+			description: "List background sessions owned by this conversation, newest first. Optionally filter by phase and limit the number of results.",
+			digest: contractDigest("background.list"),
+			id: "background.list",
+			idempotency: "supported",
+			inputSchema: Object.freeze({
+				additionalProperties: false,
+				properties: Object.freeze({
+					limit: {
+						type: "integer",
+						minimum: 1,
+						maximum: 50
+					},
+					phase: {
+						enum: [
+							"queued",
+							"running",
+							"waiting",
+							"input-required",
+							"stopping",
+							"stopped",
+							"completed",
+							"failed",
+							"reconciliation-required"
+						],
+						type: "string"
+					}
+				}),
+				type: "object"
+			}),
+			pluginId: BACKGROUND_SESSION_TOOL_PLUGIN_ID,
+			risk: "observe",
+			version: BACKGROUND_SESSION_TOOL_VERSION
+		}),
+		Object.freeze({
+			description: "Return the current phase, step counts, wake time, and result of one background session owned by this conversation.",
+			digest: contractDigest("background.status"),
+			id: "background.status",
+			idempotency: "supported",
+			inputSchema: Object.freeze({
+				additionalProperties: false,
+				properties: Object.freeze({ sessionId: {
+					type: "string",
+					minLength: 1,
+					maxLength: 200
+				} }),
+				required: ["sessionId"],
+				type: "object"
+			}),
+			pluginId: BACKGROUND_SESSION_TOOL_PLUGIN_ID,
+			risk: "observe",
+			version: BACKGROUND_SESSION_TOOL_VERSION
+		}),
+		Object.freeze({
+			description: "Send new user instruction text to a background session owned by this conversation and wake it. The input is delivered exactly once in the next step.",
+			digest: contractDigest("background.send"),
+			id: "background.send",
+			idempotency: "supported",
+			inputSchema: Object.freeze({
+				additionalProperties: false,
+				properties: Object.freeze({
+					message: {
+						type: "string",
+						minLength: 1,
+						maxLength: 2e4
+					},
+					sessionId: {
+						type: "string",
+						minLength: 1,
+						maxLength: 200
+					}
+				}),
+				required: ["message", "sessionId"],
+				type: "object"
+			}),
+			pluginId: BACKGROUND_SESSION_TOOL_PLUGIN_ID,
+			risk: "mutate",
+			version: BACKGROUND_SESSION_TOOL_VERSION
+		}),
+		Object.freeze({
+			description: "Stop a background session owned by this conversation. Persists the cancellation, aborts the active step and its owned process, and delivers a terminal notice.",
+			digest: contractDigest("background.stop"),
+			id: "background.stop",
+			idempotency: "supported",
+			inputSchema: Object.freeze({
+				additionalProperties: false,
+				properties: Object.freeze({
+					reason: {
+						type: "string",
+						maxLength: 500
+					},
+					sessionId: {
+						type: "string",
+						minLength: 1,
+						maxLength: 200
+					}
+				}),
+				required: ["sessionId"],
+				type: "object"
+			}),
+			pluginId: BACKGROUND_SESSION_TOOL_PLUGIN_ID,
+			risk: "mutate",
+			version: BACKGROUND_SESSION_TOOL_VERSION
+		})
+	];
+}
+function backgroundSessionToolIds() {
+	return [...BACKGROUND_SESSION_TOOL_IDS];
+}
+function isBackgroundSessionToolId(toolId) {
+	return BACKGROUND_SESSION_TOOL_IDS.includes(toolId);
+}
+function extendBackgroundSessionDefinition(definition) {
+	const contracts = createBackgroundSessionToolContracts();
+	const existingIds = new Set(definition.tools.map(({ id }) => id));
+	const additions = contracts.filter((contract) => !existingIds.has(contract.id));
+	const toolGrantSet = Object.freeze({
+		revision: grantRevision(definition.toolGrantSet.revision, additions.map(({ id }) => id)),
+		toolIds: Object.freeze([...definition.toolGrantSet.toolIds, ...additions.map(({ id }) => id)].sort())
+	});
+	return Object.freeze({
+		...definition,
+		tools: Object.freeze([...definition.tools, ...additions]),
+		toolGrantSet
+	});
+}
+function narrowBackgroundSessionDefinition(definition) {
+	const childToolIds = definition.toolGrantSet.toolIds.filter((id) => id !== BACKGROUND_SESSION_START_TOOL_ID);
+	const toolGrantSet = Object.freeze({
+		revision: grantRevision(definition.toolGrantSet.revision, childToolIds),
+		toolIds: Object.freeze(childToolIds)
+	});
+	return Object.freeze({
+		...definition,
+		tools: Object.freeze(definition.tools.filter(({ id }) => id !== BACKGROUND_SESSION_START_TOOL_ID)),
+		toolGrantSet
+	});
+}
+function grantRevision(parentRevision, toolIds) {
+	return `sha256:${createHash("sha256").update(JSON.stringify({
+		parentRevision,
+		toolIds: [...toolIds].sort()
+	})).digest("hex")}`;
+}
+function contractDigest(toolId) {
+	return `sha256:${createHash("sha256").update(`background-tool:${toolId}:${BACKGROUND_SESSION_TOOL_VERSION}`).digest("hex")}`;
+}
+//#endregion
 //#region src/application/plugin/deep-freeze.ts
 function deepFreeze(value) {
 	if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
@@ -70,7 +292,7 @@ function createRivusPluginCatalog() {
 		})
 	};
 }
-function resolveRivusAgentDefinition(catalog, deployment) {
+function resolveRivusAgentDefinition(catalog, deployment, options = {}) {
 	const snapshot = catalog.snapshot();
 	const plugin = snapshot.plugins.find((candidate) => candidate.id === deployment.pluginId);
 	if (!plugin) throw new InvalidRivusPlugin(`unknown deployment plugin: ${deployment.pluginId}`);
@@ -135,7 +357,7 @@ function resolveRivusAgentDefinition(catalog, deployment) {
 		}),
 		skillIds
 	});
-	return deepFreeze({
+	const definition = deepFreeze({
 		agentId: deployment.agentId,
 		endpointIds: [...deployment.endpointIds],
 		memory: {
@@ -153,6 +375,8 @@ function resolveRivusAgentDefinition(catalog, deployment) {
 		toolGrantSet,
 		tools
 	});
+	if (options.backgroundSessions === true) return extendBackgroundSessionDefinition(definition);
+	return definition;
 }
 function validateMemoryScopes(scopes, owner) {
 	const result = /* @__PURE__ */ new Set();
@@ -209,4 +433,4 @@ function stableJson(value) {
 	return JSON.stringify(value);
 }
 //#endregion
-export { resolveRivusAgentDefinition as n, deepFreeze as r, createRivusPluginCatalog as t };
+export { BACKGROUND_SESSION_START_TOOL_ID as a, BACKGROUND_SESSION_TOOL_VERSION as c, createBackgroundSessionStepSourceMessageId as d, createBackgroundSessionToolContracts as f, narrowBackgroundSessionDefinition as h, BACKGROUND_SESSION_SESSION_KEY_PREFIX as i, backgroundSessionToolIds as l, isBackgroundSessionToolId as m, resolveRivusAgentDefinition as n, BACKGROUND_SESSION_TOOL_IDS as o, extendBackgroundSessionDefinition as p, deepFreeze as r, BACKGROUND_SESSION_TOOL_PLUGIN_ID as s, createRivusPluginCatalog as t, createBackgroundSessionKey as u };

package/dist/rivus-plugin.d.ts

@@ -16,6 +16,12 @@ interface RivusPluginManifest {
 interface RivusToolExecutor {
   execute(input: unknown, context: RivusToolExecutionContext): unknown;
 }
+interface RivusToolExecutionOrigin {
+  readonly endpointId: string;
+  readonly tenantKey: string;
+  readonly conversationId?: string;
+  readonly allowedActorOpenIds: ReadonlyArray<string>;
+}
 interface RivusToolExecutionContext {
   readonly agentId: string;
   readonly instanceId: string;
@@ -27,6 +33,8 @@ interface RivusToolExecutionContext {
   readonly toolId: string;
   readonly toolVersion: string;
   readonly sessionKey: string;
+  readonly origin?: RivusToolExecutionOrigin;
+  readonly sourceMessageId?: string;
 }
 interface RivusToolFactoryContext {
   readonly toolId: string;

package/dist/tool-input-digest.js

@@ -64,6 +64,7 @@ var InvalidInvocationAuthority = class extends Error {
 };
 function createInvocationAuthority(authority) {
 	if (!authority.sourceMessageId.trim()) throw new InvalidInvocationAuthority("invocation authority requires a trusted source message id");
+	if (authority.endpointId !== void 0 && !authority.endpointId.trim()) throw new InvalidInvocationAuthority("invocation authority requires a trusted endpoint id");
 	const reference = Object.freeze({ id: `authority:${randomUUID()}` });
 	const memory = authority.memory ? Object.freeze({
 		...authority.memory,
@@ -71,6 +72,7 @@ function createInvocationAuthority(authority) {
 	}) : void 0;
 	authorities.set(reference, Object.freeze({
 		...authority,
+		...authority.allowedActorOpenIds ? { allowedActorOpenIds: Object.freeze([...authority.allowedActorOpenIds]) } : {},
 		...memory ? { memory } : {}
 	}));
 	return reference;

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.1",
+  "version": "0.7.0",
   "description": "A local agent daemon core built around a usable agent harness and domain events.",
   "type": "module",
   "license": "MIT",