@rivus/agent 0.6.2 → 0.7.0

package/dist/pi-tool-proxy.d.ts

@@ -94,6 +94,9 @@ interface InvocationAuthorityRef {
 }
 interface InvocationAuthority {
   readonly agentId: string;
+  readonly allowedActorOpenIds?: ReadonlyArray<string>;
+  readonly conversationId?: string;
+  readonly endpointId?: string;
   readonly instanceId: string;
   readonly memory?: AgentMemoryAuthority;
   readonly runId: string;

package/dist/pi.js

@@ -88,6 +88,9 @@ function createPiToolProxyDefinitions(options) {
 				const result = await options.broker.execute({
 					authority: createInvocationAuthority({
 						agentId: options.agentId,
+						allowedActorOpenIds: invocation.allowedActorOpenIds,
+						...invocation.memory?.conversationId ? { conversationId: invocation.memory.conversationId } : {},
+						endpointId: invocation.endpointId,
 						instanceId: options.instanceId,
 						...invocation.memory ? { memory: {
 							...invocation.memory,

package/dist/rivus-daemon-cli.js

@@ -1,5 +1,5 @@
 import { t as MEMORY_SCOPES } from "./agent-memory.js";
-import { n as resolveRivusAgentDefinition, r as deepFreeze, t as createRivusPluginCatalog } from "./rivus-plugin-registry.js";
+import { h as narrowBackgroundSessionDefinition, n as resolveRivusAgentDefinition, r as deepFreeze, t as createRivusPluginCatalog } from "./rivus-plugin-registry.js";
 import { createRequire } from "node:module";
 import { Effect } from "effect";
 import { createHash, randomUUID } from "node:crypto";
@@ -109,7 +109,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 +224,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 +663,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 +704,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 +841,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 +853,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 +1251,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 +1276,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 +1359,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 +1372,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 +1387,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 +1436,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 +1475,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 +1516,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 +1537,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 +1602,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 +1627,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 +1768,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 +3083,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 +3235,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,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;