@rivus/agent 0.6.2 → 0.8.0

package/README.md

@@ -15,6 +15,7 @@ The first milestone is intentionally narrow: make the agent loop and agent harne
 - Multi-agent Host primitives with trusted Endpoint bindings, stable Runtime Generation/Instance identities, lazy per-instance Runtime pooling, isolated active-run gates, and restart restoration from persisted registry records.
 - Scoped Agent Memory with a single-writer append-only JSONL adapter, explicit Profile/Deployment grants, Host-bound tenant/subject/conversation/project/audience identity, and a provider-neutral `rivus_memory` Tool wired into the Pi manifest Runtime. Agent-private proposals survive process replacement; group invocations may access only Conversation and confirmed Project Memory, and Shared Profile reads expose only confirmed records. Bound Project Memory is recalled automatically with deterministic limits; durable confirmation UX, typed Shared Profile fields, full provenance/retention metadata, and durable Compaction are still separate work.
 - Manifest-driven fixed-time Agent Automations with daily or weekday-only schedules, stable Mandate/Tick identity, per-template Tool grant narrowing, isolated Runtime and invocation authority, a durable single-writer JSON Tick adapter that records the actual Agent Run, generated-before-delivery recovery, and idempotent proactive Feishu interactive-card delivery. The first Markdown heading becomes the card title while the remaining Markdown stays scannable in the card body. Revisioned Plugin State and the general Delivery Outbox remain composable domain primitives.
+- Opt-in background Agent Sessions (`manifest.backgroundSessions`): the model decides from ordinary natural language that work should continue in the background, calls the generic `background.start` Host Tool, and the foreground Run and card end promptly. A deployment-owned supervisor runs bounded steps on an isolated Runtime lane per Agent with the exact Agent/Profile/Project Space/Skills/Memory policy and a grant narrowed to exclude `background.start`; sessions wait durably (`background.wait`), wake, receive user input once (`background.send`), stop safely, and survive daemon restart on the same stable session and Pi transcript. Progress and one terminal result are delivered idempotently to the trusted source conversation. ACP runtimes reach the same Host Tools through a built-in MCP bridge (`@rivus/agent/mcp`), so Pi and ACP backends share the identical domain, supervisor, persistence, status, and delivery semantics. The Runtime contains no business scenario, meeting, or job code — no pre-model intent router exists.
 - Peer Delegation and Subagent coordination primitives with explicit edges, hop/budget limits, monotonic ToolGrantSet intersection, isolated child authority, denied ambient sender/private-memory/Shell capabilities, and parent cancellation cascading.
 - `@rivus/agent/testing` Conformance TestKit with a reusable Fake Plugin and checks for registration/reference failures, ToolGrantSet expansion, and lifecycle disposal leaks.
 - Effect-based `AgentHarness` use case with result-oriented `prompt()`, turn-oriented `promptTurn()`, event-oriented `stream()`, text-oriented `streamText()`, event-handling `promptWithEvents()`, active-run/run/session state and transcript lookup APIs, and a default runtime factory.
@@ -125,6 +126,17 @@ For a manifest-driven multi-agent deployment, keep `rivus.config.json`, its lock
       }
     }
   ],
+  "backgroundSessions": {
+    "enabled": false,
+    "required": false,
+    "stepTimeoutMs": 300000,
+    "maxConcurrentSessions": 4,
+    "leaseMs": 30000,
+    "leaseRenewalIntervalMs": 10000,
+    "maxConsecutiveFailures": 3,
+    "retryBackoffMs": 30000,
+    "sessionLifetimeMs": 86400000
+  },
   "endpoints": [
     {
       "id": "research-feishu",

package/dist/acp.d.ts

@@ -78,12 +78,23 @@ declare function createAcpAgentServer(options: AcpAgentServerOptions): acp.Agent
 declare function serveAcpAgentOnStdio(app: acp.AgentApp): Promise<void>;
 //#endregion
 //#region src/infrastructure/acp/acp-stdio-agent-loop.d.ts
+interface AcpMcpServerEnvironmentVariable {
+  readonly name: string;
+  readonly value: string;
+}
+interface AcpMcpServer {
+  readonly args: ReadonlyArray<string>;
+  readonly command: string;
+  readonly env: ReadonlyArray<AcpMcpServerEnvironmentVariable>;
+  readonly name: string;
+}
 interface AcpStdioAgentLoopOptions {
   readonly arguments?: ReadonlyArray<string>;
   readonly clientName?: string;
   readonly command: string;
   readonly environment?: Readonly<Record<string, string>>;
   readonly initializationTimeoutMs?: number;
+  readonly mcpServers?: (input: AgentLoopInput) => ReadonlyArray<AcpMcpServer>;
   readonly onStderr?: (text: string) => void;
   readonly permissionPolicy?: AcpSessionPermissionPolicy;
   readonly terminationTimeoutMs?: number;

package/dist/acp.js

@@ -251,6 +251,19 @@ async function decideAcpPermission(request, policy) {
 }
 //#endregion
 //#region src/infrastructure/acp/acp-stdio-agent-loop.ts
+async function buildAcpSession(processConnection, options, input) {
+	const builder = processConnection.connection.agent.buildSession(options.workingDirectory);
+	for (const server of options.mcpServers?.(input) ?? []) builder.withMcpServer({
+		args: [...server.args],
+		command: server.command,
+		env: server.env.map(({ name, value }) => ({
+			name,
+			value
+		})),
+		name: server.name
+	});
+	return builder.start();
+}
 function createAcpStdioAgentLoop(options) {
 	let pendingConnection;
 	let activeConnection;
@@ -317,7 +330,7 @@ function createAcpStdioAgentLoop(options) {
 					current.dispose();
 					processConnection.sessions.delete(input.sessionKey);
 				}
-				const session = new SdkAcpAgentSession(await processConnection.connection.agent.buildSession(options.workingDirectory).start(), processConnection.connection.agent);
+				const session = new SdkAcpAgentSession(await buildAcpSession(processConnection, options, input), processConnection.connection.agent);
 				sessionKeys.set(session.sessionId, input.sessionKey);
 				processConnection.sessions.set(input.sessionKey, session);
 				return session;

package/dist/agent-loop.d.ts

@@ -296,7 +296,16 @@ interface AutomationAgentInvocationOrigin {
   readonly tenantKey: "automation";
   readonly tickId: string;
 }
-type AgentInvocationOrigin = FeishuAgentInvocationOrigin | LocalCliAgentInvocationOrigin | AutomationAgentInvocationOrigin;
+interface BackgroundSessionAgentInvocationOrigin {
+  readonly allowedActorOpenIds: ReadonlyArray<string>;
+  readonly endpointId: string;
+  readonly kind: "background-session";
+  readonly memory?: AgentMemoryInvocationIdentity;
+  readonly sessionId: string;
+  readonly sourceMessageId: string;
+  readonly tenantKey: string;
+}
+type AgentInvocationOrigin = FeishuAgentInvocationOrigin | LocalCliAgentInvocationOrigin | AutomationAgentInvocationOrigin | BackgroundSessionAgentInvocationOrigin;
 //#endregion
 //#region src/application/agent/agent-loop.d.ts
 interface AgentLoopInput {

package/dist/background-session-authority.js

@@ -0,0 +1,224 @@
+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
+export { BACKGROUND_SESSION_TOOL_VERSION as a, createBackgroundSessionStepSourceMessageId as c, isBackgroundSessionToolId as d, narrowBackgroundSessionDefinition as f, BACKGROUND_SESSION_TOOL_PLUGIN_ID as i, createBackgroundSessionToolContracts as l, BACKGROUND_SESSION_START_TOOL_ID as n, backgroundSessionToolIds as o, BACKGROUND_SESSION_TOOL_IDS as r, createBackgroundSessionKey as s, BACKGROUND_SESSION_SESSION_KEY_PREFIX as t, extendBackgroundSessionDefinition as u };

package/dist/background-session-input.js

@@ -0,0 +1,45 @@
+//#region src/application/background-session/background-session-input.ts
+function readBackgroundSessionObject(input, allowed, error) {
+	if (input === null || typeof input !== "object" || Array.isArray(input)) throw error("background tool input must be an object");
+	const record = input;
+	const unknown = Object.keys(record).find((key) => !allowed.includes(key));
+	if (unknown) throw error(`field is not allowed: ${unknown}`);
+	return record;
+}
+function readBackgroundSessionString(value, name, error) {
+	if (typeof value !== "string" || value.trim() === "") throw error(`${name} must be a non-empty string`);
+	return value;
+}
+function readBackgroundSessionInteger(value, name, error) {
+	if (!Number.isSafeInteger(value) || value < 1) throw error(`${name} must be a positive integer`);
+	return value;
+}
+function readBackgroundSessionPhase(value, error) {
+	const phases = [
+		"queued",
+		"running",
+		"waiting",
+		"input-required",
+		"stopping",
+		"stopped",
+		"completed",
+		"failed",
+		"reconciliation-required"
+	];
+	if (typeof value !== "string" || !phases.includes(value)) throw error(`phase must be one of ${phases.join(", ")}`);
+	return value;
+}
+function readBackgroundSessionWaitInput(input, error) {
+	const { delayMs, reason, until } = readBackgroundSessionObject(input, [
+		"delayMs",
+		"reason",
+		"until"
+	], error);
+	const args = {};
+	if (delayMs !== void 0) args.delayMs = readBackgroundSessionInteger(delayMs, "delayMs", error);
+	if (reason !== void 0) args.reason = readBackgroundSessionString(reason, "reason", error);
+	if (until !== void 0) args.until = readBackgroundSessionString(until, "until", error);
+	return args;
+}
+//#endregion
+export { readBackgroundSessionWaitInput as a, readBackgroundSessionString as i, readBackgroundSessionObject as n, readBackgroundSessionPhase as r, readBackgroundSessionInteger as t };

package/dist/background-session-service.d.ts

@@ -0,0 +1,291 @@
+import { c as MemoryScope, n as AgentMemoryIdentity } from "./agent-memory.js";
+import { b as RivusResolvedToolDescriptor, c as ResolvedRivusAgentDefinition, w as RivusToolExecutionContext } from "./rivus-plugin.js";
+
+//#region src/domain/background-agent-session.d.ts
+type BackgroundSessionId = string;
+type BackgroundSessionPhase = "queued" | "running" | "waiting" | "input-required" | "stopping" | "stopped" | "completed" | "failed" | "reconciliation-required";
+declare function isBackgroundSessionTerminalPhase(phase: BackgroundSessionPhase): boolean;
+interface BackgroundSessionLease {
+  readonly owner: string;
+  readonly epoch: number;
+  readonly expiresAt: string;
+}
+interface BackgroundSessionOrigin {
+  readonly endpointId: string;
+  readonly tenantKey: string;
+  readonly conversationId?: string;
+  readonly allowedActorOpenIds: ReadonlyArray<string>;
+  readonly memory?: AgentMemoryIdentity;
+}
+interface BackgroundSessionAuthority {
+  readonly agentId: string;
+  readonly profileRevision: string;
+  readonly toolGrantRevision: string;
+  readonly policyEpoch: number;
+  readonly memoryScopes: ReadonlyArray<MemoryScope>;
+  readonly projectSpaceId?: string;
+  readonly sessionKey: string;
+}
+interface BackgroundSessionTerminalResult {
+  readonly text: string;
+  readonly stepRunId: string;
+  readonly completedAt: string;
+}
+interface BackgroundSessionCancellation {
+  readonly reason: string;
+  readonly requestedAt: string;
+}
+interface BackgroundSessionState {
+  readonly sessionId: BackgroundSessionId;
+  readonly displayName: string;
+  readonly phase: BackgroundSessionPhase;
+  readonly revision: number;
+  readonly parentRunId: string;
+  readonly sourceMessageId: string;
+  readonly origin: BackgroundSessionOrigin;
+  readonly authority: BackgroundSessionAuthority;
+  readonly prompt: string;
+  readonly stepCount: number;
+  readonly wakeCount: number;
+  readonly currentStepRunId?: string;
+  readonly lastWakeText?: string;
+  readonly pendingInput: ReadonlyArray<string>;
+  readonly wakeAt?: string;
+  readonly lease?: BackgroundSessionLease;
+  readonly cancellation?: BackgroundSessionCancellation;
+  readonly consecutiveFailures: number;
+  readonly result?: BackgroundSessionTerminalResult;
+  readonly errorMessage?: string;
+  readonly reconciliationNote?: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+declare class BackgroundSessionTransitionDenied extends Error {
+  readonly sessionId: BackgroundSessionId;
+  readonly name = "BackgroundSessionTransitionDenied";
+  constructor(sessionId: BackgroundSessionId, message: string);
+}
+interface CreateBackgroundSessionInput {
+  readonly sessionId: BackgroundSessionId;
+  readonly displayName: string;
+  readonly prompt: string;
+  readonly parentRunId: string;
+  readonly sourceMessageId: string;
+  readonly origin: BackgroundSessionOrigin;
+  readonly authority: BackgroundSessionAuthority;
+  readonly now: string;
+}
+declare function createBackgroundSession(input: CreateBackgroundSessionInput): BackgroundSessionState;
+interface ClaimBackgroundSessionInput {
+  readonly lease: BackgroundSessionLease;
+  readonly stepRunId: string;
+  readonly wakeText: string;
+  readonly now: string;
+}
+declare function claimBackgroundSession(state: BackgroundSessionState, input: ClaimBackgroundSessionInput): BackgroundSessionState;
+declare function renewBackgroundSessionLease(state: BackgroundSessionState, lease: BackgroundSessionLease): BackgroundSessionState;
+declare function releaseBackgroundSessionLease(state: BackgroundSessionState): BackgroundSessionState;
+interface SuspendBackgroundSessionInput {
+  readonly wakeAt?: string;
+  readonly reason?: string;
+  readonly now: string;
+}
+declare function suspendBackgroundSession(state: BackgroundSessionState, input: SuspendBackgroundSessionInput): BackgroundSessionState;
+declare function completeBackgroundSessionStep(state: BackgroundSessionState, input: {
+  readonly text: string;
+  readonly stepRunId: string;
+  readonly now: string;
+}): BackgroundSessionState;
+declare function failBackgroundSessionStep(state: BackgroundSessionState, input: {
+  readonly errorMessage: string;
+  readonly now: string;
+  readonly retryable: boolean;
+  readonly wakeAt?: string;
+}): BackgroundSessionState;
+declare function requestBackgroundSessionStop(state: BackgroundSessionState, input: {
+  readonly reason: string;
+  readonly now: string;
+}): BackgroundSessionState;
+declare function completeBackgroundSessionStop(state: BackgroundSessionState, input: {
+  readonly now: string;
+}): BackgroundSessionState;
+declare function parkBackgroundSessionForReconciliation(state: BackgroundSessionState, input: {
+  readonly reason: string;
+  readonly now: string;
+}): BackgroundSessionState;
+declare function resolveBackgroundSessionReconciliation(state: BackgroundSessionState, input: {
+  readonly outcome: "continue" | "stop";
+  readonly now: string;
+}): BackgroundSessionState;
+declare function appendBackgroundSessionInput(state: BackgroundSessionState, input: {
+  readonly message: string;
+  readonly now: string;
+}): BackgroundSessionState;
+declare function requeueInterruptedBackgroundSessionStep(state: BackgroundSessionState, input: {
+  readonly wakeText: string;
+  readonly now: string;
+}): BackgroundSessionState;
+declare function isBackgroundSessionLeaseExpired(state: BackgroundSessionState, now: string): boolean;
+declare function isBackgroundSessionDue(state: BackgroundSessionState, now: string): boolean;
+//#endregion
+//#region src/application/background-session/background-session-repository.d.ts
+interface BackgroundSessionLeasePrecondition {
+  readonly kind: "absent";
+}
+interface BackgroundSessionLeaseRequirement {
+  readonly kind: "held";
+  readonly owner: string;
+  readonly epoch: number;
+}
+interface BackgroundSessionLeaseStaleOrAbsent {
+  readonly kind: "absent-or-stale";
+}
+interface BackgroundSessionRepository {
+  create(state: BackgroundSessionState): Promise<BackgroundSessionState>;
+  get(sessionId: string): Promise<BackgroundSessionState | undefined>;
+  list(options?: {
+    readonly phase?: BackgroundSessionPhase;
+    readonly limit?: number;
+  }): Promise<ReadonlyArray<BackgroundSessionState>>;
+  update(input: {
+    readonly sessionId: string;
+    readonly expectedRevision: number;
+    readonly expectedLease?: BackgroundSessionLeasePrecondition | BackgroundSessionLeaseRequirement | BackgroundSessionLeaseStaleOrAbsent;
+    readonly now?: string;
+    readonly build: (state: BackgroundSessionState) => BackgroundSessionState;
+  }): Promise<BackgroundSessionState | undefined>;
+}
+declare class BackgroundSessionRepositoryConflict extends Error {
+  readonly name = "BackgroundSessionRepositoryConflict";
+  constructor(sessionId: string, message: string);
+}
+declare class BackgroundSessionRepositoryCorrupted extends Error {
+  readonly name = "BackgroundSessionRepositoryCorrupted";
+}
+interface CreateBackgroundSessionRepositoryOptions {
+  readonly initial?: ReadonlyArray<BackgroundSessionState>;
+  readonly persist?: (state: BackgroundSessionState) => Promise<void>;
+}
+declare function createBackgroundSessionRepository(options?: CreateBackgroundSessionRepositoryOptions): BackgroundSessionRepository;
+//#endregion
+//#region src/application/background-session/background-session-delivery-store.d.ts
+type BackgroundSessionDeliveryKind = "progress" | "final" | "stopped" | "failed" | "reconciliation";
+interface BackgroundSessionDeliveryRecord {
+  readonly deliveryId: string;
+  readonly sessionId: string;
+  readonly kind: BackgroundSessionDeliveryKind;
+  readonly text: string;
+  readonly state: "pending" | "delivered";
+  readonly revision: number;
+  readonly providerMessageId?: string;
+  readonly createdAt: string;
+}
+interface BackgroundSessionDeliveryStore {
+  enqueue(input: {
+    readonly deliveryId: string;
+    readonly sessionId: string;
+    readonly kind: BackgroundSessionDeliveryKind;
+    readonly text: string;
+    readonly createdAt: string;
+  }): Promise<BackgroundSessionDeliveryRecord>;
+  pending(): Promise<ReadonlyArray<BackgroundSessionDeliveryRecord>>;
+  markDelivered(deliveryId: string, providerMessageId: string): Promise<BackgroundSessionDeliveryRecord | undefined>;
+}
+declare class BackgroundSessionDeliveryConflict extends Error {
+  readonly name = "BackgroundSessionDeliveryConflict";
+  constructor(deliveryId: string, message: string);
+}
+interface CreateBackgroundSessionDeliveryStoreOptions {
+  readonly initial?: ReadonlyArray<BackgroundSessionDeliveryRecord>;
+  readonly persist?: (record: BackgroundSessionDeliveryRecord) => Promise<void>;
+}
+declare function createBackgroundSessionDeliveryStore(options?: CreateBackgroundSessionDeliveryStoreOptions): BackgroundSessionDeliveryStore;
+//#endregion
+//#region src/application/background-session/background-session-authority.d.ts
+declare const BACKGROUND_SESSION_TOOL_IDS: readonly ["background.start", "background.wait", "background.list", "background.status", "background.send", "background.stop"];
+declare const BACKGROUND_SESSION_START_TOOL_ID = "background.start";
+declare const BACKGROUND_SESSION_TOOL_PLUGIN_ID = "rivus-core";
+declare const BACKGROUND_SESSION_TOOL_VERSION = "1.0.0";
+declare const BACKGROUND_SESSION_SESSION_KEY_PREFIX = "background";
+declare function createBackgroundSessionKey(sessionId: string): string;
+declare function createBackgroundSessionStepSourceMessageId(sessionId: string, stepCount: number): string;
+interface BackgroundSessionToolContract extends RivusResolvedToolDescriptor {}
+declare function createBackgroundSessionToolContracts(): ReadonlyArray<BackgroundSessionToolContract>;
+declare function backgroundSessionToolIds(): ReadonlyArray<string>;
+declare function isBackgroundSessionToolId(toolId: string): boolean;
+declare function extendBackgroundSessionDefinition(definition: ResolvedRivusAgentDefinition): ResolvedRivusAgentDefinition;
+declare function narrowBackgroundSessionDefinition(definition: ResolvedRivusAgentDefinition): ResolvedRivusAgentDefinition;
+//#endregion
+//#region src/application/background-session/background-session-service.d.ts
+interface BackgroundSessionSummary {
+  readonly sessionId: string;
+  readonly displayName: string;
+  readonly phase: BackgroundSessionPhase;
+  readonly stepCount: number;
+  readonly wakeAt?: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+interface BackgroundSessionDetail extends BackgroundSessionSummary {
+  readonly parentRunId: string;
+  readonly pendingInput: ReadonlyArray<string>;
+  readonly result?: BackgroundSessionState["result"];
+  readonly errorMessage?: string;
+  readonly cancellationReason?: string;
+  readonly reconciliationNote?: string;
+}
+declare class BackgroundSessionCallerDenied extends Error {
+  readonly name = "BackgroundSessionCallerDenied";
+  constructor(message: string);
+}
+interface BackgroundSessionServiceOptions {
+  readonly clock: {
+    now(): string;
+  };
+  readonly deliveries: BackgroundSessionDeliveryStore;
+  readonly repository: BackgroundSessionRepository;
+}
+interface BackgroundSessionService {
+  list(input: {
+    readonly context: RivusToolExecutionContext;
+    readonly limit?: number;
+    readonly phase?: BackgroundSessionPhase;
+  }): Promise<ReadonlyArray<BackgroundSessionSummary>>;
+  resolveReconciliation(input: {
+    readonly outcome: "continue" | "stop";
+    readonly sessionId: string;
+  }): Promise<BackgroundSessionSummary>;
+  send(input: {
+    readonly context: RivusToolExecutionContext;
+    readonly message: string;
+    readonly sessionId: string;
+  }): Promise<BackgroundSessionSummary>;
+  start(input: {
+    readonly authority: BackgroundSessionAuthority;
+    readonly context: RivusToolExecutionContext;
+    readonly displayName?: string;
+    readonly prompt: string;
+    readonly sessionId: string;
+  }): Promise<BackgroundSessionSummary>;
+  status(input: {
+    readonly context: RivusToolExecutionContext;
+    readonly sessionId: string;
+  }): Promise<BackgroundSessionDetail>;
+  stop(input: {
+    readonly context: RivusToolExecutionContext;
+    readonly reason?: string;
+    readonly sessionId: string;
+  }): Promise<BackgroundSessionSummary>;
+  wait(input: {
+    readonly context: RivusToolExecutionContext;
+    readonly delayMs?: number;
+    readonly reason?: string;
+    readonly until?: string;
+  }): Promise<BackgroundSessionSummary>;
+}
+declare function createBackgroundSessionService(options: BackgroundSessionServiceOptions): BackgroundSessionService;
+declare function sessionIdFromSessionKey(sessionKey: string): string | undefined;
+declare function terminalDeliveryId(sessionId: string, kind: BackgroundSessionDeliveryKind): string;
+declare function progressDeliveryId(sessionId: string, stepCount: number): string;
+//#endregion
+export { suspendBackgroundSession as $, BackgroundSessionCancellation as A, completeBackgroundSessionStep as B, BackgroundSessionDeliveryStore as C, BackgroundSessionRepositoryCorrupted as D, BackgroundSessionRepositoryConflict as E, BackgroundSessionState as F, isBackgroundSessionLeaseExpired as G, createBackgroundSession as H, BackgroundSessionTerminalResult as I, releaseBackgroundSessionLease as J, isBackgroundSessionTerminalPhase as K, BackgroundSessionTransitionDenied as L, BackgroundSessionLease as M, BackgroundSessionOrigin as N, createBackgroundSessionRepository as O, BackgroundSessionPhase as P, resolveBackgroundSessionReconciliation as Q, appendBackgroundSessionInput as R, BackgroundSessionDeliveryRecord as S, BackgroundSessionRepository as T, failBackgroundSessionStep as U, completeBackgroundSessionStop as V, isBackgroundSessionDue as W, requestBackgroundSessionStop as X, renewBackgroundSessionLease as Y, requeueInterruptedBackgroundSessionStep as Z, createBackgroundSessionToolContracts as _, createBackgroundSessionService as a, narrowBackgroundSessionDefinition as b, terminalDeliveryId as c, BACKGROUND_SESSION_TOOL_IDS as d, BACKGROUND_SESSION_TOOL_PLUGIN_ID as f, createBackgroundSessionStepSourceMessageId as g, createBackgroundSessionKey as h, BackgroundSessionSummary as i, BackgroundSessionId as j, BackgroundSessionAuthority as k, BACKGROUND_SESSION_SESSION_KEY_PREFIX as l, backgroundSessionToolIds as m, BackgroundSessionDetail as n, progressDeliveryId as o, BACKGROUND_SESSION_TOOL_VERSION as p, parkBackgroundSessionForReconciliation as q, BackgroundSessionService as r, sessionIdFromSessionKey as s, BackgroundSessionCallerDenied as t, BACKGROUND_SESSION_START_TOOL_ID as u, extendBackgroundSessionDefinition as v, createBackgroundSessionDeliveryStore as w, BackgroundSessionDeliveryConflict as x, isBackgroundSessionToolId as y, claimBackgroundSession as z };

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { D as loadRivusDeploymentManifest, G as validateRivusDeploymentManifest, H as loadMergedLocalEnvFile, T as resolveNodeRivusPluginModulePath, V as resolveFeishuEndpointCredentials, t as runRivusDaemonCli } from "./rivus-daemon-cli.js";
+import { D as loadRivusDeploymentManifest, T as resolveNodeRivusPluginModulePath, X as resolveFeishuEndpointCredentials, Z as loadMergedLocalEnvFile, et as validateRivusDeploymentManifest, t as runRivusDaemonCli } from "./rivus-daemon-cli.js";
 import { Effect } from "effect";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";