@rivus/agent 0.6.2 → 0.8.0

package/dist/rivus-daemon-cli.js

@@ -1,4 +1,5 @@
 import { t as MEMORY_SCOPES } from "./agent-memory.js";
+import { f as narrowBackgroundSessionDefinition } from "./background-session-authority.js";
 import { n as resolveRivusAgentDefinition, r as deepFreeze, t as createRivusPluginCatalog } from "./rivus-plugin-registry.js";
 import { createRequire } from "node:module";
 import { Effect } from "effect";
@@ -109,7 +110,7 @@ async function loadRivusDeployment(options) {
 			continue;
 		}
 		try {
-			const baseDefinition = resolveRivusAgentDefinition(catalog, agent);
+			const baseDefinition = resolveRivusAgentDefinition(catalog, agent, { backgroundSessions: options.manifest.backgroundSessions?.enabled === true });
 			const projectSpace = agent.projectSpaceId ? options.manifest.projectSpaces?.find(({ id }) => id === agent.projectSpaceId) : void 0;
 			const definition = projectSpace ? deepFreeze({
 				...baseDefinition,
@@ -224,6 +225,13 @@ function validateRivusDeploymentManifest(manifest) {
 	if (!defaultEndpoint) throw new Error(`default endpoint does not exist: ${manifest.defaultEndpointId}`);
 	if (defaultEndpoint.agentId !== defaultAgent.agentId) throw new Error("default endpoint is not bound to the default agent");
 	if (!defaultEndpoint.enabled) throw new Error("default endpoint must be enabled");
+	if (manifest.backgroundSessions) validateBackgroundSessions(manifest.backgroundSessions);
+}
+function validateBackgroundSessions(config) {
+	if (config.required && !config.enabled) throw new Error("backgroundSessions.required requires backgroundSessions.enabled");
+	if (config.leaseRenewalIntervalMs >= config.leaseMs) throw new Error("backgroundSessions.leaseRenewalIntervalMs must be shorter than leaseMs");
+	if (config.stepTimeoutMs <= 0 || config.maxConcurrentSessions <= 0 || config.leaseMs <= 0) throw new Error("backgroundSessions durations and concurrency must be positive");
+	if (config.retryBackoffMs <= 0 || config.sessionLifetimeMs <= 0 || config.maxConsecutiveFailures <= 0) throw new Error("backgroundSessions retry and lifetime limits must be positive");
 }
 function validateRelativeProjectPath(value, owner) {
 	if (value.trim() === "" || isAbsolute(value) || value.includes("\0")) throw new Error(`${owner} must be a non-empty relative path`);
@@ -656,6 +664,19 @@ function createCounters() {
 	};
 }
 //#endregion
+//#region src/application/background-session/background-session-config.ts
+const DEFAULT_BACKGROUND_SESSION_STEP_TIMEOUT_MS = 300 * 1e3;
+const DEFAULT_BACKGROUND_SESSION_MAX_CONCURRENT_SESSIONS = 4;
+const DEFAULT_BACKGROUND_SESSION_LEASE_MS = 3e4;
+const DEFAULT_BACKGROUND_SESSION_LEASE_RENEWAL_INTERVAL_MS = 1e4;
+const DEFAULT_BACKGROUND_SESSION_MAX_CONSECUTIVE_FAILURES = 3;
+const DEFAULT_BACKGROUND_SESSION_RETRY_BACKOFF_MS = 3e4;
+const DEFAULT_BACKGROUND_SESSION_LIFETIME_MS = 1440 * 60 * 1e3;
+const DEFAULT_BACKGROUND_SESSION_SUPERVISOR_INTERVAL_MS = 1e3;
+function resolveBackgroundSessionSupervisorIntervalMs(leaseMs) {
+	return Math.min(5e3, Math.max(200, Math.floor(leaseMs / 10)));
+}
+//#endregion
 //#region src/infrastructure/config/rivus-deployment-manifest.ts
 var RivusDeploymentManifestError = class extends Error {
 	manifestPath;
@@ -684,12 +705,17 @@ function parseManifest(value) {
 	exactKeys(root, [
 		"agents",
 		"automations",
+		"backgroundSessions",
 		"defaultAgentId",
 		"defaultEndpointId",
 		"endpoints",
 		"plugins",
 		"projectSpaces"
-	], "manifest", ["automations", "projectSpaces"]);
+	], "manifest", [
+		"automations",
+		"backgroundSessions",
+		"projectSpaces"
+	]);
 	const plugins = array(root.plugins, "manifest.plugins").map((entry, index) => {
 		const plugin = record(entry, `manifest.plugins[${index}]`);
 		exactKeys(plugin, [
@@ -816,9 +842,11 @@ function parseManifest(value) {
 			workingDirectory: string(projectSpace.workingDirectory, `manifest.projectSpaces[${index}].workingDirectory`)
 		});
 	});
+	const backgroundSessions = root.backgroundSessions === void 0 ? void 0 : parseBackgroundSessions(record(root.backgroundSessions, "manifest.backgroundSessions"));
 	return Object.freeze({
 		agents: Object.freeze(agents),
 		automations: Object.freeze(automations),
+		...backgroundSessions ? { backgroundSessions } : {},
 		defaultAgentId: string(root.defaultAgentId, "manifest.defaultAgentId"),
 		defaultEndpointId: string(root.defaultEndpointId, "manifest.defaultEndpointId"),
 		endpoints: Object.freeze(endpoints),
@@ -826,6 +854,38 @@ function parseManifest(value) {
 		projectSpaces: Object.freeze(projectSpaces)
 	});
 }
+function parseBackgroundSessions(value) {
+	exactKeys(value, [
+		"enabled",
+		"leaseMs",
+		"leaseRenewalIntervalMs",
+		"maxConsecutiveFailures",
+		"maxConcurrentSessions",
+		"required",
+		"retryBackoffMs",
+		"sessionLifetimeMs",
+		"stepTimeoutMs"
+	], "manifest.backgroundSessions", [
+		"leaseMs",
+		"leaseRenewalIntervalMs",
+		"maxConsecutiveFailures",
+		"maxConcurrentSessions",
+		"retryBackoffMs",
+		"sessionLifetimeMs",
+		"stepTimeoutMs"
+	]);
+	return Object.freeze({
+		enabled: boolean(value.enabled, "manifest.backgroundSessions.enabled"),
+		required: boolean(value.required, "manifest.backgroundSessions.required"),
+		stepTimeoutMs: positiveInteger(value.stepTimeoutMs ?? 3e5, "manifest.backgroundSessions.stepTimeoutMs"),
+		maxConcurrentSessions: positiveInteger(value.maxConcurrentSessions ?? 4, "manifest.backgroundSessions.maxConcurrentSessions"),
+		leaseMs: positiveInteger(value.leaseMs ?? 3e4, "manifest.backgroundSessions.leaseMs"),
+		leaseRenewalIntervalMs: positiveInteger(value.leaseRenewalIntervalMs ?? 1e4, "manifest.backgroundSessions.leaseRenewalIntervalMs"),
+		maxConsecutiveFailures: positiveInteger(value.maxConsecutiveFailures ?? 3, "manifest.backgroundSessions.maxConsecutiveFailures"),
+		retryBackoffMs: positiveInteger(value.retryBackoffMs ?? 3e4, "manifest.backgroundSessions.retryBackoffMs"),
+		sessionLifetimeMs: positiveInteger(value.sessionLifetimeMs ?? 864e5, "manifest.backgroundSessions.sessionLifetimeMs")
+	});
+}
 function record(value, path) {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${path} must be an object`);
 	return value;
@@ -1192,7 +1252,7 @@ function createAgentInstanceRegistry(options = {}) {
 			skillGrantRevision: definition.skillGrantSet.revision,
 			toolGrantRevision: definition.toolGrantSet.revision
 		});
-		const bindingId = binding.kind === "endpoint" ? binding.endpointId : binding.automationId;
+		const bindingId = binding.kind === "endpoint" ? binding.endpointId : binding.kind === "automation" ? binding.automationId : binding.agentId;
 		const bindingKey = `${binding.kind}:${bindingId}:${definition.agentId}`;
 		const existing = records.get(bindingKey);
 		if (existing) {
@@ -1217,6 +1277,10 @@ function createAgentInstanceRegistry(options = {}) {
 			automationId,
 			kind: "automation"
 		}, definition),
+		resolveBackgroundSession: (agentId, definition) => resolveBinding({
+			agentId,
+			kind: "background-session"
+		}, definition),
 		resolveEndpoint: (endpointId, definition) => resolveBinding({
 			endpointId,
 			kind: "endpoint"
@@ -1296,6 +1360,7 @@ function createRivusAgentHost(options) {
 	const definitions = new Map(options.definitions.map((definition) => [definition.agentId, definition]));
 	const endpoints = /* @__PURE__ */ new Map();
 	const automations = /* @__PURE__ */ new Map();
+	const backgroundSessions = /* @__PURE__ */ new Map();
 	for (const endpoint of options.endpoints) {
 		if (endpoints.has(endpoint.id)) throw new InvalidRivusEndpointBinding(`duplicate endpoint: ${endpoint.id}`);
 		const definition = definitions.get(endpoint.agentId);
@@ -1308,6 +1373,11 @@ function createRivusAgentHost(options) {
 		if (!definitions.has(automation.definition.agentId)) throw new InvalidRivusEndpointBinding(`unknown automation agent: ${automation.definition.agentId}`);
 		automations.set(automation.id, options.runtimePool.registry.resolveAutomation(automation.id, automation.definition));
 	}
+	for (const backgroundSession of options.backgroundSessions ?? []) {
+		if (backgroundSessions.has(backgroundSession.agentId)) throw new InvalidRivusEndpointBinding(`duplicate background session agent: ${backgroundSession.agentId}`);
+		if (!definitions.has(backgroundSession.agentId)) throw new InvalidRivusEndpointBinding(`unknown background session agent: ${backgroundSession.agentId}`);
+		backgroundSessions.set(backgroundSession.agentId, options.runtimePool.registry.resolveBackgroundSession(backgroundSession.agentId, backgroundSession.definition));
+	}
 	const resolveEndpoint = (endpointId) => {
 		const instance = endpoints.get(endpointId);
 		if (!instance) throw new InvalidRivusEndpointBinding(`unknown endpoint: ${endpointId}`);
@@ -1318,11 +1388,19 @@ function createRivusAgentHost(options) {
 		if (!instance) throw new InvalidRivusEndpointBinding(`unknown automation: ${automationId}`);
 		return instance;
 	};
+	const resolveBackgroundSession = (agentId) => {
+		const instance = backgroundSessions.get(agentId);
+		if (!instance) throw new InvalidRivusEndpointBinding(`unknown background session agent: ${agentId}`);
+		return instance;
+	};
 	return {
+		cancelBackgroundSession: (agentId, input) => options.runtimePool.cancel(resolveBackgroundSession(agentId), input),
 		cancelEndpoint: (endpointId, input) => options.runtimePool.cancel(resolveEndpoint(endpointId), input),
 		handleAutomation: (automationId, input) => options.runtimePool.run(resolveAutomation(automationId), input),
+		handleBackgroundSession: (agentId, input) => options.runtimePool.run(resolveBackgroundSession(agentId), input),
 		handleEndpoint: (endpointId, input) => options.runtimePool.run(resolveEndpoint(endpointId), input),
 		resolveAutomation,
+		resolveBackgroundSession,
 		resolveEndpoint
 	};
 }
@@ -1359,9 +1437,15 @@ async function createRivusDeploymentDaemon(options) {
 	})));
 	const definitions = new Map(deployment.definitions.map((definition) => [definition.agentId, definition]));
 	const automationDefinitions = new Map(deployment.automationDefinitions.map((definition) => [definition.id, definition]));
+	const backgroundSessionsConfig = deployment.manifest.backgroundSessions;
+	const backgroundDefinitions = /* @__PURE__ */ new Map();
+	if (backgroundSessionsConfig?.enabled) for (const agent of deployment.agents) {
+		if (agent.status !== "enabled" || !agent.definition) continue;
+		backgroundDefinitions.set(agent.agentId, narrowBackgroundSessionDefinition(agent.definition));
+	}
 	const runtimePool = createAgentRuntimePool({
 		createRuntime: (instance) => {
-			const definition = instance.binding.kind === "automation" ? automationDefinitions.get(instance.binding.automationId)?.runtimeDefinition : definitions.get(instance.agentId);
+			const definition = instance.binding.kind === "automation" ? automationDefinitions.get(instance.binding.automationId)?.runtimeDefinition : instance.binding.kind === "background-session" ? backgroundDefinitions.get(instance.agentId) : definitions.get(instance.agentId);
 			if (!definition) throw new RivusDeploymentDaemonLifecycleError(`runtime instance references unknown agent: ${instance.agentId}`);
 			const projectSpace = definition.projectSpaceId ? projectSpaces.get(definition.projectSpaceId) : void 0;
 			return options.createRuntime({
@@ -1392,11 +1476,20 @@ async function createRivusDeploymentDaemon(options) {
 			lifecycle: definition.enabled && agentEnabled ? "stopped" : "disabled"
 		};
 	});
+	const backgroundSessionSlot = backgroundSessionsConfig ? {
+		agentEnabled: backgroundDefinitions.size > 0,
+		definition: backgroundSessionsConfig,
+		lifecycle: backgroundSessionsConfig.enabled && backgroundDefinitions.size > 0 ? "stopped" : "disabled"
+	} : void 0;
 	const host = createRivusAgentHost({
 		automations: automationSlots.filter((slot) => slot.definition.enabled && slot.agentEnabled && slot.resolvedDefinition !== void 0).map((slot) => ({
 			definition: slot.resolvedDefinition.runtimeDefinition,
 			id: slot.definition.id
 		})),
+		...backgroundSessionSlot ? { backgroundSessions: [...backgroundDefinitions].map(([agentId, definition]) => ({
+			agentId,
+			definition
+		})) } : {},
 		definitions: deployment.definitions,
 		endpoints: slots.filter((slot) => slot.definition.enabled && slot.agentEnabled).map((slot) => ({
 			agentId: slot.definition.agentId,
@@ -1424,7 +1517,15 @@ async function createRivusDeploymentDaemon(options) {
 		agentId: slot.definition.agentId,
 		automationId: slot.definition.id
 	});
-	const allSlots = [...slots, ...automationSlots];
+	const backgroundSessionStatus = (slot) => Object.freeze({
+		...componentStatus(slot),
+		...slot.adapter?.status ? { supervisor: slot.adapter.status() } : {}
+	});
+	const allSlots = [
+		...slots,
+		...automationSlots,
+		...backgroundSessionSlot ? [backgroundSessionSlot] : []
+	];
 	const isReady = () => allSlots.every(isSlotReady);
 	const failedRequiredEndpointIds = () => slots.filter((slot) => slot.definition.enabled && slot.definition.required && slot.lifecycle !== "running").map((slot) => slot.definition.id);
 	const failedRequiredAutomationIds = () => automationSlots.filter((slot) => slot.definition.enabled && slot.definition.required && slot.lifecycle !== "running").map((slot) => slot.definition.id);
@@ -1437,6 +1538,7 @@ async function createRivusDeploymentDaemon(options) {
 	const status = () => Object.freeze({
 		agents: deployment.agents,
 		automations: Object.freeze(automationSlots.map(automationStatus)),
+		...backgroundSessionSlot ? { backgroundSessions: backgroundSessionStatus(backgroundSessionSlot) } : {},
 		defaultAgentId: deployment.manifest.defaultAgentId,
 		defaultEndpointId: deployment.manifest.defaultEndpointId,
 		endpoints: Object.freeze(slots.map(endpointStatus)),
@@ -1501,6 +1603,18 @@ async function createRivusDeploymentDaemon(options) {
 				});
 				degraded ||= slotDegraded;
 			}
+			if (backgroundSessionSlot) {
+				const slotDegraded = await startSlot(backgroundSessionSlot, true, async () => {
+					if (!options.createBackgroundSession) throw new RivusDeploymentDaemonLifecycleError("deployment bootstrap does not provide Background Session adapters");
+					return options.createBackgroundSession({
+						agentIds: [...backgroundDefinitions.keys()],
+						cancel: (input) => host.cancelBackgroundSession(input.agentId, input),
+						config: backgroundSessionSlot.definition,
+						run: (input) => host.handleBackgroundSession(input.agentId, input)
+					});
+				});
+				degraded ||= slotDegraded;
+			}
 			lifecycle = degraded ? "degraded" : "running";
 			assertRequiredReadiness();
 		},
@@ -1514,6 +1628,7 @@ async function createRivusDeploymentDaemon(options) {
 			lifecycle = "stopping";
 			const errors = [];
 			await stopSlots(automationSlots, errors);
+			if (backgroundSessionSlot) await stopSlots([backgroundSessionSlot], errors);
 			await stopSlots(slots, errors);
 			try {
 				await runtimePool.disposeAll();
@@ -1654,6 +1769,7 @@ async function createConfiguredRivusDeploymentDaemon(options) {
 	const manifest = await loadRivusDeploymentManifest(options.manifestPath, options.manifestOptions);
 	return createRivusDeploymentDaemon({
 		...options.createAutomation ? { createAutomation: options.createAutomation } : {},
+		...options.createBackgroundSession ? { createBackgroundSession: options.createBackgroundSession } : {},
 		createEndpoint: options.createEndpoint,
 		createRuntime: options.createRuntime,
 		deploymentRoot: dirname(options.manifestPath),
@@ -2968,6 +3084,17 @@ function toRedactedDeploymentManifest(manifest) {
 			templateId,
 			timeZone
 		})),
+		...manifest.backgroundSessions ? { backgroundSessions: {
+			enabled: manifest.backgroundSessions.enabled,
+			leaseMs: manifest.backgroundSessions.leaseMs,
+			leaseRenewalIntervalMs: manifest.backgroundSessions.leaseRenewalIntervalMs,
+			maxConsecutiveFailures: manifest.backgroundSessions.maxConsecutiveFailures,
+			maxConcurrentSessions: manifest.backgroundSessions.maxConcurrentSessions,
+			required: manifest.backgroundSessions.required,
+			retryBackoffMs: manifest.backgroundSessions.retryBackoffMs,
+			sessionLifetimeMs: manifest.backgroundSessions.sessionLifetimeMs,
+			stepTimeoutMs: manifest.backgroundSessions.stepTimeoutMs
+		} } : {},
 		defaultAgentId: manifest.defaultAgentId,
 		defaultEndpointId: manifest.defaultEndpointId,
 		endpoints: manifest.endpoints.map(({ agentId, credentialRef, enabled, id, required, sessionNamespace }) => ({
@@ -3109,4 +3236,4 @@ function hasRecoveryRunner(daemon) {
 	return typeof daemon.openRecoveryControl === "function";
 }
 //#endregion
-export { CardPresentationTransitionDenied as A, FeishuEndpointCredentialError as B, loadRivusDaemonConfig as C, loadRivusDeploymentManifest as D, RivusDeploymentManifestError as E, completeCardPresentationHandoff as F, validateRivusDeploymentManifest as G, loadMergedLocalEnvFile as H, createCardPresentationChain as I, failCardPresentationHandoff as L, activeCardPresentation as M, beginCardPresentationHandoff as N, DEFAULT_CARD_STREAM_LEASE_MS as O, compensateCardPresentationHandoff as P, isCardPresentationHandoffDue as R, RivusDaemonConfigError as S, resolveNodeRivusPluginModulePath as T, RivusPluginLoadError as U, resolveFeishuEndpointCredentials as V, loadRivusDeployment as W, createStableId as _, InvalidRivusProjectSpace as a, createRivusEnvFromOpenClawConfig as b, RivusDeploymentReadinessError as c, createRivusAgentHost as d, AgentInstanceBusy as f, createAgentInstanceRegistry as g, AgentInstanceConflict as h, resolveRivusProjectSpace as i, acceptsCardPresentationProgress as j, createFeishuCardRollover as k, createRivusDeploymentDaemon as l, createAgentRuntimePool as m, createRivusDeploymentCliProcess as n, RivusDeploymentAutomationReadinessError as o, AgentRuntimeDisposed as p, createConfiguredRivusDeploymentDaemon as r, RivusDeploymentDaemonLifecycleError as s, runRivusDaemonCli as t, InvalidRivusEndpointBinding as u, createRivusDaemonShutdownController as v, loadNodeRivusPluginModule as w, formatRivusEnvFile as x, OpenClawEnvImportError as y, markCardPresentationTerminal as z };
+export { loadRivusDeployment as $, DEFAULT_BACKGROUND_SESSION_LIFETIME_MS as A, acceptsCardPresentationProgress as B, loadRivusDaemonConfig as C, loadRivusDeploymentManifest as D, RivusDeploymentManifestError as E, DEFAULT_BACKGROUND_SESSION_SUPERVISOR_INTERVAL_MS as F, createCardPresentationChain as G, beginCardPresentationHandoff as H, resolveBackgroundSessionSupervisorIntervalMs as I, markCardPresentationTerminal as J, failCardPresentationHandoff as K, DEFAULT_CARD_STREAM_LEASE_MS as L, DEFAULT_BACKGROUND_SESSION_MAX_CONSECUTIVE_FAILURES as M, DEFAULT_BACKGROUND_SESSION_RETRY_BACKOFF_MS as N, DEFAULT_BACKGROUND_SESSION_LEASE_MS as O, DEFAULT_BACKGROUND_SESSION_STEP_TIMEOUT_MS as P, RivusPluginLoadError as Q, createFeishuCardRollover as R, RivusDaemonConfigError as S, resolveNodeRivusPluginModulePath as T, compensateCardPresentationHandoff as U, activeCardPresentation as V, completeCardPresentationHandoff as W, resolveFeishuEndpointCredentials as X, FeishuEndpointCredentialError as Y, loadMergedLocalEnvFile as Z, createStableId as _, InvalidRivusProjectSpace as a, createRivusEnvFromOpenClawConfig as b, RivusDeploymentReadinessError as c, createRivusAgentHost as d, validateRivusDeploymentManifest as et, AgentInstanceBusy as f, createAgentInstanceRegistry as g, AgentInstanceConflict as h, resolveRivusProjectSpace as i, DEFAULT_BACKGROUND_SESSION_MAX_CONCURRENT_SESSIONS as j, DEFAULT_BACKGROUND_SESSION_LEASE_RENEWAL_INTERVAL_MS as k, createRivusDeploymentDaemon as l, createAgentRuntimePool as m, createRivusDeploymentCliProcess as n, RivusDeploymentAutomationReadinessError as o, AgentRuntimeDisposed as p, isCardPresentationHandoffDue as q, createConfiguredRivusDeploymentDaemon as r, RivusDeploymentDaemonLifecycleError as s, runRivusDaemonCli as t, InvalidRivusEndpointBinding as u, createRivusDaemonShutdownController as v, loadNodeRivusPluginModule as w, formatRivusEnvFile as x, OpenClawEnvImportError as y, CardPresentationTransitionDenied as z };

package/dist/rivus-plugin-registry.js

@@ -1,4 +1,5 @@
 import { c as InvalidRivusPlugin, o as createRivusMemoryToolContract, r as RIVUS_MEMORY_TOOL_PLUGIN_ID, t as MEMORY_SCOPES } from "./agent-memory.js";
+import { u as extendBackgroundSessionDefinition } from "./background-session-authority.js";
 import { createHash } from "node:crypto";
 //#region src/application/plugin/deep-freeze.ts
 function deepFreeze(value) {
@@ -70,7 +71,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 +136,7 @@ function resolveRivusAgentDefinition(catalog, deployment) {
 		}),
 		skillIds
 	});
-	return deepFreeze({
+	const definition = deepFreeze({
 		agentId: deployment.agentId,
 		endpointIds: [...deployment.endpointIds],
 		memory: {
@@ -153,6 +154,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();

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.2",
+  "version": "0.8.0",
   "description": "A local agent daemon core built around a usable agent harness and domain events.",
   "type": "module",
   "license": "MIT",
@@ -41,6 +41,10 @@
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "import": "./dist/testing/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js"
     }
   },
   "files": [