@rivus/agent 0.5.1 → 0.6.0

package/dist/rivus-daemon-cli.js

@@ -313,6 +313,331 @@ function required$1(env, variable) {
 	return value;
 }
 //#endregion
+//#region src/domain/card-presentation.ts
+var CardPresentationTransitionDenied = class extends Error {
+	name = "CardPresentationTransitionDenied";
+};
+const STREAMING_STATUSES = /* @__PURE__ */ new Set(["streaming", "active"]);
+function createCardPresentationChain(binding) {
+	assertTimestamp(binding.createdAt, "presentation creation time");
+	assertTimestamp(binding.leaseDeadlineAt, "presentation lease deadline");
+	return {
+		activeGeneration: 0,
+		activePresentationId: binding.presentationId,
+		presentations: [{
+			cardId: binding.cardId,
+			createdAt: binding.createdAt,
+			...binding.elementId === void 0 ? {} : { elementId: binding.elementId },
+			generation: 0,
+			leaseDeadlineAt: binding.leaseDeadlineAt,
+			presentationId: binding.presentationId,
+			runId: binding.runId,
+			sourceMessageId: binding.sourceMessageId,
+			status: "streaming"
+		}],
+		revision: 1,
+		runId: binding.runId
+	};
+}
+function activeCardPresentation(chain) {
+	const presentation = chain.presentations.find((candidate) => candidate.presentationId === chain.activePresentationId);
+	if (!presentation) throw new CardPresentationTransitionDenied(`presentation chain ${chain.runId} has no active presentation`);
+	return presentation;
+}
+function acceptsCardPresentationProgress(chain) {
+	return STREAMING_STATUSES.has(activeCardPresentation(chain).status);
+}
+function isCardPresentationHandoffDue(chain, now) {
+	const presentation = activeCardPresentation(chain);
+	return STREAMING_STATUSES.has(presentation.status) && Date.parse(presentation.leaseDeadlineAt) <= Date.parse(now);
+}
+function beginCardPresentationHandoff(chain, handoffAt) {
+	assertTimestamp(handoffAt, "handoff time");
+	const presentation = activeCardPresentation(chain);
+	if (presentation.status === "handoff-pending") return chain;
+	if (!STREAMING_STATUSES.has(presentation.status)) throw new CardPresentationTransitionDenied(`presentation ${presentation.presentationId} is ${presentation.status} and cannot start a handoff`);
+	return replaceActivePresentation(chain, {
+		...presentation,
+		handoffAt,
+		status: "handoff-pending"
+	});
+}
+function completeCardPresentationHandoff(chain, successor) {
+	assertTimestamp(successor.createdAt, "successor creation time");
+	assertTimestamp(successor.leaseDeadlineAt, "successor lease deadline");
+	const predecessor = activeCardPresentation(chain);
+	if (predecessor.status !== "handoff-pending") throw new CardPresentationTransitionDenied(`presentation ${predecessor.presentationId} is ${predecessor.status} and cannot adopt a successor`);
+	if (predecessor.successorPresentationId !== void 0) throw new CardPresentationTransitionDenied(`presentation ${predecessor.presentationId} already has successor ${predecessor.successorPresentationId}`);
+	const generation = chain.activeGeneration + 1;
+	return {
+		...chain,
+		activeGeneration: generation,
+		activePresentationId: successor.presentationId,
+		presentations: [...chain.presentations.map((candidate) => candidate.presentationId === predecessor.presentationId ? {
+			...predecessor,
+			status: "closed",
+			successorPresentationId: successor.presentationId
+		} : candidate), {
+			cardId: successor.cardId,
+			createdAt: successor.createdAt,
+			...successor.elementId === void 0 ? {} : { elementId: successor.elementId },
+			generation,
+			leaseDeadlineAt: successor.leaseDeadlineAt,
+			predecessorPresentationId: predecessor.presentationId,
+			presentationId: successor.presentationId,
+			runId: chain.runId,
+			sourceMessageId: predecessor.sourceMessageId,
+			status: "active"
+		}],
+		revision: chain.revision + 1
+	};
+}
+function failCardPresentationHandoff(chain, failedAt) {
+	assertTimestamp(failedAt, "handoff failure time");
+	const presentation = activeCardPresentation(chain);
+	if (presentation.status !== "handoff-pending") throw new CardPresentationTransitionDenied(`presentation ${presentation.presentationId} is ${presentation.status} and has no pending handoff`);
+	return replaceActivePresentation(chain, {
+		...presentation,
+		handoffFailedAt: failedAt,
+		status: "closed"
+	});
+}
+function compensateCardPresentationHandoff(chain, compensatedAt) {
+	return activeCardPresentation(chain).status === "handoff-pending" ? failCardPresentationHandoff(chain, compensatedAt) : chain;
+}
+function markCardPresentationTerminal(chain, terminalReceiptId) {
+	if (terminalReceiptId.trim().length === 0) throw new CardPresentationTransitionDenied("terminal receipt id must not be empty");
+	const presentation = activeCardPresentation(chain);
+	if (presentation.status === "terminal") return chain;
+	return replaceActivePresentation(chain, {
+		...presentation,
+		status: "terminal",
+		terminalReceiptId
+	});
+}
+function replaceActivePresentation(chain, presentation) {
+	return {
+		...chain,
+		presentations: chain.presentations.map((candidate) => candidate.presentationId === presentation.presentationId ? presentation : candidate),
+		revision: chain.revision + 1
+	};
+}
+function assertTimestamp(value, label) {
+	if (Number.isNaN(Date.parse(value))) throw new CardPresentationTransitionDenied(`${label} must be an ISO timestamp`);
+}
+//#endregion
+//#region src/application/feishu/feishu-card-rollover.ts
+const DEFAULT_CARD_STREAM_LEASE_MS = 51e4;
+function createFeishuCardRollover(options) {
+	const leaseMs = options.leaseMs ?? 51e4;
+	if (!Number.isSafeInteger(leaseMs) || leaseMs < 1) throw new Error("Feishu card stream lease must be a positive integer");
+	const counters = createCounters();
+	const liveRuns = /* @__PURE__ */ new Map();
+	const semaphore = Effect.unsafeMakeSemaphore(1);
+	const exclusive = (effect) => semaphore.withPermits(1)(effect);
+	const record = (event, at) => {
+		counters[event.type] += 1;
+		options.observe?.({
+			...event,
+			at: at.toISOString()
+		});
+	};
+	const recordNow = (event) => options.clock.now.pipe(Effect.map((at) => record(event, at)));
+	const leaseDeadline = (at) => new Date(at.getTime() + leaseMs).toISOString();
+	const presentationId = (runId, generation) => `${runId}#${generation}`;
+	const publishProgress = (action) => Effect.suspend(() => {
+		const chain = options.store.chain(action.runId);
+		if (chain && acceptsCardPresentationProgress(chain)) return options.publisher.publish(action);
+		return recordNow({
+			...chain ? {
+				generation: chain.activeGeneration,
+				presentationId: chain.activePresentationId
+			} : {},
+			runId: action.runId,
+			type: "stale_update_dropped"
+		});
+	});
+	const publishTerminal = (action) => options.publisher.publish(action).pipe(Effect.tapError((error) => recordNow({
+		error,
+		runId: action.runId,
+		type: "terminal_delivery_failed"
+	})), Effect.tap(() => options.store.markTerminal({
+		runId: action.runId,
+		terminalReceiptId: `${action.runId}:${action.type}`
+	}).pipe(Effect.catchAll((error) => recordNow({
+		error,
+		runId: action.runId,
+		type: "presentation_write_failed"
+	})))), Effect.ensuring(Effect.sync(() => {
+		liveRuns.delete(action.runId);
+	})));
+	const publishAction = (action) => {
+		switch (action.type) {
+			case "update_text": return publishProgress(action);
+			case "handoff": return options.publisher.publish(action);
+			default: return publishTerminal(action);
+		}
+	};
+	const runHandoff = (runId) => Effect.gen(function* () {
+		const run = liveRuns.get(runId);
+		if (!run) return {
+			reason: "not-live",
+			status: "skipped"
+		};
+		const startedAt = yield* options.clock.now;
+		const chain = options.store.chain(runId);
+		if (!chain || !isCardPresentationHandoffDue(chain, startedAt.toISOString())) return {
+			reason: "not-due",
+			status: "skipped"
+		};
+		const start = yield* options.store.beginHandoff({
+			handoffAt: startedAt.toISOString(),
+			runId
+		}).pipe(Effect.catchAll(() => Effect.succeed(void 0)));
+		if (!start) return {
+			reason: "not-streaming",
+			status: "skipped"
+		};
+		if (!start.started) return {
+			reason: "already-pending",
+			status: "skipped"
+		};
+		const predecessor = start.presentation;
+		const generation = predecessor.generation + 1;
+		record({
+			cardId: predecessor.cardId,
+			generation,
+			presentationId: predecessor.presentationId,
+			runId,
+			sourceMessageId: predecessor.sourceMessageId,
+			type: "handoff_started"
+		}, startedAt);
+		const successorId = presentationId(runId, generation);
+		const created = yield* options.createSuccessor({
+			generation,
+			presentationId: successorId,
+			run
+		}).pipe(Effect.map((target) => ({ target })), Effect.catchAll((error) => options.store.failHandoff({
+			failedAt: startedAt.toISOString(),
+			runId
+		}).pipe(Effect.catchAll((storeError) => recordNow({
+			error: storeError,
+			runId,
+			type: "presentation_write_failed"
+		})), Effect.flatMap(() => recordNow({
+			cardId: predecessor.cardId,
+			error,
+			generation,
+			presentationId: predecessor.presentationId,
+			runId,
+			type: "handoff_failed"
+		})), Effect.as({ error }))));
+		if ("error" in created) return {
+			error: created.error,
+			status: "failed"
+		};
+		yield* options.publisher.publish({
+			runId,
+			type: "handoff"
+		}).pipe(Effect.catchAll((error) => recordNow({
+			cardId: predecessor.cardId,
+			error,
+			generation,
+			runId,
+			type: "handoff_notice_failed"
+		})));
+		const adoptedAt = yield* options.clock.now;
+		const presentation = yield* options.store.completeHandoff({
+			runId,
+			successor: {
+				cardId: created.target.cardId,
+				createdAt: adoptedAt.toISOString(),
+				...created.target.elementId === void 0 ? {} : { elementId: created.target.elementId },
+				leaseDeadlineAt: leaseDeadline(adoptedAt),
+				presentationId: successorId
+			}
+		});
+		record({
+			cardId: predecessor.cardId,
+			generation,
+			presentationId: successorId,
+			runId,
+			sourceMessageId: predecessor.sourceMessageId,
+			successorCardId: created.target.cardId,
+			type: "handoff_succeeded"
+		}, adoptedAt);
+		return {
+			presentation,
+			status: "rolled-over"
+		};
+	});
+	return {
+		bindRun: (run, target) => exclusive(Effect.gen(function* () {
+			const createdAt = yield* options.clock.now;
+			const presentation = yield* options.store.bind({
+				cardId: target.cardId,
+				createdAt: createdAt.toISOString(),
+				...target.elementId === void 0 ? {} : { elementId: target.elementId },
+				leaseDeadlineAt: leaseDeadline(createdAt),
+				presentationId: presentationId(run.runId, 0),
+				runId: run.runId,
+				sourceMessageId: run.messageId
+			});
+			liveRuns.set(run.runId, run);
+			return presentation;
+		})),
+		dueRunIds: (now) => {
+			const nowIso = now.toISOString();
+			return [...liveRuns.keys()].filter((runId) => {
+				const chain = options.store.chain(runId);
+				return chain !== void 0 && isCardPresentationHandoffDue(chain, nowIso);
+			});
+		},
+		flush: (runId) => exclusive(options.publisher.flush(runId)),
+		handoff: (runId) => exclusive(runHandoff(runId)),
+		observeStreamClosed: (cardId) => {
+			counters.stream_closed += 1;
+			options.observe?.({
+				cardId,
+				type: "stream_closed"
+			});
+		},
+		publish: (action) => exclusive(publishAction(action)),
+		recover: () => exclusive(Effect.gen(function* () {
+			const compensatedAt = yield* options.clock.now;
+			const compensated = yield* options.store.compensateInterruptedHandoffs(compensatedAt.toISOString());
+			for (const chain of compensated) record({
+				generation: chain.activeGeneration,
+				presentationId: chain.activePresentationId,
+				runId: chain.runId,
+				type: "handoff_failed"
+			}, compensatedAt);
+			return { compensated: compensated.length };
+		})),
+		status: () => ({
+			counters: { ...counters },
+			leaseMs,
+			live: [...liveRuns.keys()].flatMap((runId) => {
+				const chain = options.store.chain(runId);
+				if (!chain) return [];
+				return chain.presentations.filter((presentation) => presentation.presentationId === chain.activePresentationId);
+			})
+		})
+	};
+}
+function createCounters() {
+	return {
+		handoff_failed: 0,
+		handoff_notice_failed: 0,
+		handoff_started: 0,
+		handoff_succeeded: 0,
+		presentation_write_failed: 0,
+		stale_update_dropped: 0,
+		stream_closed: 0,
+		terminal_delivery_failed: 0
+	};
+}
+//#endregion
 //#region src/infrastructure/config/rivus-deployment-manifest.ts
 var RivusDeploymentManifestError = class extends Error {
 	manifestPath;
@@ -397,6 +722,7 @@ function parseManifest(value) {
 		exactKeys(endpoint, [
 			"agentId",
 			"baseUrl",
+			"cardStreamLeaseMs",
 			"credentialRef",
 			"enabled",
 			"experimental",
@@ -405,12 +731,13 @@ function parseManifest(value) {
 			"required",
 			"sessionNamespace",
 			"streamMinIntervalMs"
-		], `manifest.endpoints[${index}]`, ["experimental"]);
+		], `manifest.endpoints[${index}]`, ["cardStreamLeaseMs", "experimental"]);
 		const experimental = endpoint.experimental === void 0 ? void 0 : record(endpoint.experimental, `manifest.endpoints[${index}].experimental`);
 		if (experimental) exactKeys(experimental, ["cotMessages"], `manifest.endpoints[${index}].experimental`);
 		return Object.freeze({
 			agentId: string(endpoint.agentId, `manifest.endpoints[${index}].agentId`),
 			baseUrl: string(endpoint.baseUrl, `manifest.endpoints[${index}].baseUrl`),
+			cardStreamLeaseMs: endpoint.cardStreamLeaseMs === void 0 ? DEFAULT_CARD_STREAM_LEASE_MS : positiveInteger(endpoint.cardStreamLeaseMs, `manifest.endpoints[${index}].cardStreamLeaseMs`),
 			credentialRef: string(endpoint.credentialRef, `manifest.endpoints[${index}].credentialRef`),
 			enabled: boolean(endpoint.enabled, `manifest.endpoints[${index}].enabled`),
 			...experimental ? { experimental: Object.freeze({ cotMessages: boolean(experimental.cotMessages, `manifest.endpoints[${index}].experimental.cotMessages`) }) } : {},
@@ -561,6 +888,7 @@ function loadRivusDaemonConfig(env, options = {}) {
 		const appId = yield* required(env, "FEISHU_APP_ID");
 		const appSecret = yield* required(env, "FEISHU_APP_SECRET");
 		const streamMinIntervalMs = yield* optionalPositiveInteger(env.FEISHU_STREAM_MIN_INTERVAL_MS, "FEISHU_STREAM_MIN_INTERVAL_MS", DEFAULT_STREAM_MIN_INTERVAL_MS$1);
+		const cardStreamLeaseMs = yield* optionalPositiveInteger(env.FEISHU_CARD_STREAM_LEASE_MS, "FEISHU_CARD_STREAM_LEASE_MS", DEFAULT_CARD_STREAM_LEASE_MS);
 		const thinkingLevel = yield* optionalThinkingLevel(env.PI_THINKING_LEVEL);
 		const apiKey = yield* optionalPiApiKey(env, options.readTextFile ?? readUtf8File);
 		const baseUrl = optional(env.PI_BASE_URL);
@@ -571,6 +899,7 @@ function loadRivusDaemonConfig(env, options = {}) {
 				appId,
 				appSecret,
 				baseUrl: optional(env.FEISHU_BASE_URL) ?? DEFAULT_FEISHU_BASE_URL$1,
+				cardStreamLeaseMs,
 				streamMinIntervalMs
 			},
 			pi: {
@@ -1670,6 +1999,7 @@ Options:
 Environment:
   RIVUS_BOOTSTRAP_MODULE may be used instead of --bootstrap.
   FEISHU_APP_ID and FEISHU_APP_SECRET are required by the default config loader.
+  FEISHU_CARD_STREAM_LEASE_MS shortens or extends the proactive CardKit rollover threshold.
   PI_API_KEY_FILE may point to a local BYOK key file instead of PI_API_KEY.
 `;
 const DEFAULT_WAIT_RECEIVE_TIMEOUT_MS = 3e4;
@@ -2587,6 +2917,7 @@ function toRedactedConfig(config) {
 			appIdPresent: Boolean(config.feishu.appId),
 			appSecretPresent: Boolean(config.feishu.appSecret),
 			baseUrl: config.feishu.baseUrl,
+			cardStreamLeaseMs: config.feishu.cardStreamLeaseMs,
 			streamMinIntervalMs: config.feishu.streamMinIntervalMs
 		},
 		pi: {
@@ -2760,4 +3091,4 @@ function hasRecoveryRunner(daemon) {
 	return typeof daemon.openRecoveryControl === "function";
 }
 //#endregion
-export { loadMergedLocalEnvFile as A, loadRivusDaemonConfig as C, loadRivusDeploymentManifest as D, RivusDeploymentManifestError as E, loadRivusDeployment as M, validateRivusDeploymentManifest as N, FeishuEndpointCredentialError as O, RivusDaemonConfigError as S, resolveNodeRivusPluginModulePath as T, 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, RivusPluginLoadError as j, resolveFeishuEndpointCredentials 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 };
+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 };

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

@@ -16,14 +16,14 @@ import {
   createAgentHarnessPooledRuntime,
   createRivusMemoryToolDescriptor,
   createConfiguredFeishuAutomationCardSender,
-  createConfiguredFeishuCardKitPublisher,
-  createConfiguredFeishuCardKitTargetPreparation,
+  createConfiguredFeishuCardRolloverRuntime,
   createConfiguredFeishuHumanInteractionPresenter,
   createConfiguredFeishuOpenApiClient,
   createConfiguredFeishuTextReplySender,
   createFeishuCotPublisher,
   createFeishuDeploymentEndpoint,
   createFeishuPresentationPreparation,
+  createSystemClock,
   createFeishuCardDeliveryReconciler,
   createHumanInteractionEndpointRegistry,
   createHumanInteractionService,
@@ -43,7 +43,6 @@ import {
   createRoutedHumanInteractionToolApprovalService,
   createSessionScheduler,
   createScheduledAutomation,
-  createSystemClock,
   createToolBroker,
   createUuidRunIds,
   createWorkspaceRootHandle,
@@ -61,6 +60,7 @@ import {
   type CreateRivusDeploymentAutomationInput,
   type CreateRivusDeploymentRuntimeInput,
   type ConfiguredFeishuOpenApiResponse,
+  type FeishuAgentRunPreparation,
   type FeishuWebSocketClient,
   type RivusDaemonConfig,
   type RivusDeploymentBootstrapContext,
@@ -106,6 +106,7 @@ export async function createRivusDeploymentAdapters(context: RivusDeploymentBoot
         feishu: {
           ...credentials,
           baseUrl: input.deliveryEndpoint.baseUrl,
+          cardStreamLeaseMs: input.deliveryEndpoint.cardStreamLeaseMs,
           streamMinIntervalMs: input.deliveryEndpoint.streamMinIntervalMs
         },
         pi: {}
@@ -176,6 +177,7 @@ export async function createRivusDeploymentAdapters(context: RivusDeploymentBoot
         feishu: {
           ...credentials,
           baseUrl: input.definition.baseUrl,
+          cardStreamLeaseMs: input.definition.cardStreamLeaseMs,
           streamMinIntervalMs: input.definition.streamMinIntervalMs
         },
         pi: {}
@@ -198,14 +200,20 @@ export async function createRivusDeploymentAdapters(context: RivusDeploymentBoot
           filePath: join(endpointState, "human-interactions.jsonl")
         })
       });
-      const publisher = createConfiguredFeishuCardKitPublisher({
+      const cardRollover = createConfiguredFeishuCardRolloverRuntime({
         agentName: input.agentId,
+        cardTargets,
         client: openApiClient,
+        clock: createSystemClock(),
         config,
         ledger: cardLedger,
-        resolveTarget: (runId) => cardTargets.resolveTarget(runId),
-        sleep
+        onError: (error) => {
+          console.error(`Feishu card rollover failed for endpoint ${input.endpointId}`, error);
+        },
+        sleep,
+        title: input.agentId
       });
+      const publisher = cardRollover.rollover;
       const endpointEvents = createJsonlAgentEventLog({
         filePath: join(STATE_DIR, "instances", input.instanceId, "agent-events.jsonl")
       });
@@ -220,15 +228,11 @@ export async function createRivusDeploymentAdapters(context: RivusDeploymentBoot
         client: openApiClient,
         config
       });
-      const prepareCardTarget = createConfiguredFeishuCardKitTargetPreparation({
-        client: openApiClient,
-        config,
-        registry: cardTargets,
-        title: input.agentId
-      });
+      const prepareCardTarget = (run: FeishuAgentRunPreparation) => cardRollover.prepareRun(run);
       const endpoint = createFeishuDeploymentEndpoint({
         agentId: input.agentId,
         botOpenId,
+        cardRollover: cardRollover.transport,
         cancel: input.cancel,
         endpointId: input.endpointId,
         eventDispatcher: createLazyFeishuWebSocketEventDispatcher(() => new Lark.EventDispatcher({})),

package/package.json

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