@rivus/gateway 0.16.2

package/dist/mcp.d.ts

@@ -0,0 +1,92 @@
+import { M as BackgroundSessionAuthority, r as BackgroundSessionService } from "./chunks/background-session-service.js";
+import { Readable, Writable } from "node:stream";
+
+//#region src/bootstrap/mcp/rivus-mcp-entrypoint.d.ts
+interface RunBackgroundSessionMcpServerEnv {
+  readonly fetch?: typeof fetch;
+  readonly input?: Readable;
+  readonly output?: Writable;
+}
+declare function runBackgroundSessionMcpServer(options?: RunBackgroundSessionMcpServerEnv): Promise<void>;
+//#endregion
+//#region src/core/application/background-session/control/background-session-control.d.ts
+type BackgroundSessionControlCommand = "start" | "wait" | "list" | "status" | "send" | "stop";
+interface BackgroundSessionControlOrigin {
+  readonly allowedActorOpenIds: ReadonlyArray<string>;
+  readonly conversationId?: string;
+  readonly endpointId: string;
+  readonly tenantKey: string;
+}
+interface BackgroundSessionControlContext {
+  readonly agentId: string;
+  readonly authority: BackgroundSessionAuthority;
+  readonly origin: BackgroundSessionControlOrigin;
+  readonly policyEpoch: number;
+  readonly runId: string;
+  readonly sessionKey: string;
+  readonly sourceMessageId: string;
+}
+interface BackgroundSessionControl {
+  handle(command: BackgroundSessionControlCommand, context: BackgroundSessionControlContext, input: unknown): Promise<unknown>;
+}
+declare class BackgroundSessionControlError extends Error {
+  readonly name = "BackgroundSessionControlError";
+}
+//#endregion
+//#region src/adapters/mcp/background-session/background-session-mcp-server.d.ts
+declare const BACKGROUND_SESSION_MCP_SERVER_NAME = "rivus-background-sessions";
+declare const BACKGROUND_SESSION_MCP_SERVER_VERSION = "1.0.0";
+interface BackgroundSessionMcpServerOptions {
+  readonly capability: string;
+  readonly controlUrl: string;
+  readonly controlToken: string;
+  readonly enabledTools?: ReadonlyArray<BackgroundSessionControlCommand>;
+  readonly fetch?: typeof fetch;
+  readonly input?: Readable;
+  readonly output?: Writable;
+  readonly serverName?: string;
+  readonly serverVersion?: string;
+}
+interface BackgroundSessionMcpServer {
+  run(): Promise<void>;
+}
+declare class BackgroundSessionMcpError extends Error {
+  readonly name = "BackgroundSessionMcpError";
+}
+declare function createBackgroundSessionMcpServer(options: BackgroundSessionMcpServerOptions): BackgroundSessionMcpServer;
+//#endregion
+//#region src/adapters/compatibility/background-session/control.d.ts
+declare function createBackgroundSessionControl(options: {
+  readonly service: BackgroundSessionService;
+}): BackgroundSessionControl;
+declare function toControlContext(input: {
+  readonly agentId: string;
+  readonly authority: BackgroundSessionAuthority;
+  readonly origin: BackgroundSessionControlOrigin;
+  readonly policyEpoch: number;
+  readonly sessionKey: string;
+  readonly sourceMessageId?: string;
+}): BackgroundSessionControlContext;
+//#endregion
+//#region src/adapters/http/background-session/background-session-control-http-server.d.ts
+interface BackgroundSessionControlHttpServerOptions {
+  readonly control: BackgroundSessionControl;
+  readonly host?: string;
+  readonly port: number;
+  readonly status?: () => unknown;
+  readonly token: string;
+}
+interface BackgroundSessionControlHttpServer {
+  port(): number;
+  issueCapability(context: BackgroundSessionControlContext): string;
+  close(): Promise<void>;
+  start(): Promise<void>;
+}
+declare class BackgroundSessionControlHttpError extends Error {
+  readonly statusCode: number;
+  readonly name = "BackgroundSessionControlHttpError";
+  constructor(statusCode: number, message: string);
+}
+declare function createBackgroundSessionControlHttpServer(options: BackgroundSessionControlHttpServerOptions): BackgroundSessionControlHttpServer;
+//#endregion
+export { BACKGROUND_SESSION_MCP_SERVER_NAME, BACKGROUND_SESSION_MCP_SERVER_VERSION, type BackgroundSessionControl, type BackgroundSessionControlCommand, type BackgroundSessionControlContext, BackgroundSessionControlError, BackgroundSessionControlHttpError, type BackgroundSessionControlHttpServer, type BackgroundSessionControlHttpServerOptions, type BackgroundSessionControlOrigin, BackgroundSessionMcpError, type BackgroundSessionMcpServer, type BackgroundSessionMcpServerOptions, createBackgroundSessionControl, createBackgroundSessionControlHttpServer, createBackgroundSessionMcpServer, runBackgroundSessionMcpServer, toControlContext };

package/dist/mcp.js

@@ -0,0 +1,455 @@
+import { d as createBackgroundSessionKey, o as createBackgroundSessionToolContracts } from "./chunks/background-session-authority.js";
+import { a as readBackgroundSessionWaitInput, i as readBackgroundSessionString, n as readBackgroundSessionObject, r as readBackgroundSessionPhase, t as readBackgroundSessionInteger } from "./chunks/background-session-control-input.js";
+import { createRandomId } from "@rivus/platform/identity";
+import { randomUUID } from "node:crypto";
+import { pathToFileURL } from "node:url";
+import { createServer } from "node:http";
+//#region src/adapters/mcp/background-session/background-session-mcp-server.ts
+const BACKGROUND_SESSION_MCP_SERVER_NAME = "rivus-background-sessions";
+const BACKGROUND_SESSION_MCP_SERVER_VERSION = "1.0.0";
+var BackgroundSessionMcpError = class extends Error {
+	name = "BackgroundSessionMcpError";
+};
+function createBackgroundSessionMcpServer(options) {
+	const input = options.input ?? process.stdin;
+	const output = options.output ?? process.stdout;
+	const fetchImplementation = options.fetch ?? fetch;
+	const enabledTools = new Set(options.enabledTools ?? [
+		"start",
+		"wait",
+		"list",
+		"status",
+		"send",
+		"stop"
+	]);
+	const tools = createBackgroundSessionToolContracts().filter(({ id }) => enabledTools.has(id.slice(11))).map((contract) => ({
+		description: contract.description,
+		inputSchema: contract.inputSchema,
+		name: contract.id
+	}));
+	const serverInfo = {
+		name: options.serverName ?? "rivus-background-sessions",
+		version: options.serverVersion ?? "1.0.0"
+	};
+	return { run: () => runMcpServer({
+		capability: options.capability,
+		controlToken: options.controlToken,
+		controlUrl: options.controlUrl,
+		fetchImplementation,
+		input,
+		output,
+		serverInfo,
+		tools
+	}) };
+}
+async function runMcpServer(options) {
+	const send = (message) => {
+		const body = JSON.stringify(message);
+		options.output.write(`${body}\n`);
+	};
+	for await (const message of readMcpMessages(options.input)) {
+		if (!isRecord(message) || !isJsonRpcRequestId(message.id)) continue;
+		const method = typeof message.method === "string" ? message.method : void 0;
+		if (!method) continue;
+		try {
+			switch (method) {
+				case "initialize":
+					send({
+						jsonrpc: "2.0",
+						id: message.id,
+						result: {
+							capabilities: { tools: { listChanged: false } },
+							protocolVersion: "2025-03-26",
+							serverInfo: options.serverInfo
+						}
+					});
+					break;
+				case "ping":
+					send({
+						jsonrpc: "2.0",
+						id: message.id,
+						result: {}
+					});
+					break;
+				case "tools/list":
+					send({
+						jsonrpc: "2.0",
+						id: message.id,
+						result: { tools: options.tools }
+					});
+					break;
+				case "tools/call": {
+					const params = isRecord(message.params) ? message.params : {};
+					const name = typeof params.name === "string" ? params.name : "";
+					const command = name.startsWith("background.") ? name.slice(11) : void 0;
+					if (!command || !options.tools.some((tool) => tool.name === name)) {
+						send({
+							jsonrpc: "2.0",
+							id: message.id,
+							error: {
+								code: -32602,
+								message: `unknown tool: ${name}`
+							}
+						});
+						break;
+					}
+					const response = await options.fetchImplementation(options.controlUrl, {
+						body: JSON.stringify({
+							capability: options.capability,
+							command,
+							input: params.arguments ?? {}
+						}),
+						headers: {
+							authorization: `Bearer ${options.controlToken}`,
+							"content-type": "application/json"
+						},
+						method: "POST"
+					});
+					const envelope = await response.json();
+					if (!response.ok || envelope.error) {
+						const messageText = envelope.error?.message ?? `background session control failed with ${response.status}`;
+						send({
+							jsonrpc: "2.0",
+							id: message.id,
+							error: {
+								code: -32e3,
+								message: messageText
+							}
+						});
+						break;
+					}
+					send({
+						jsonrpc: "2.0",
+						id: message.id,
+						result: {
+							content: [{
+								text: JSON.stringify(envelope.result ?? null),
+								type: "text"
+							}],
+							isError: false
+						}
+					});
+					break;
+				}
+				default: send({
+					jsonrpc: "2.0",
+					id: message.id,
+					error: {
+						code: -32601,
+						message: `method not found: ${method}`
+					}
+				});
+			}
+		} catch (error) {
+			send({
+				jsonrpc: "2.0",
+				id: message.id,
+				error: {
+					code: -32e3,
+					message: error instanceof Error ? error.message : String(error)
+				}
+			});
+		}
+	}
+}
+async function* readMcpMessages(input) {
+	let buffer = "";
+	for await (const chunk of input) {
+		buffer += chunk.toString("utf8");
+		let newlineIndex = buffer.indexOf("\n");
+		while (newlineIndex >= 0) {
+			const line = buffer.slice(0, newlineIndex).replace(/\r$/, "");
+			buffer = buffer.slice(newlineIndex + 1);
+			if (line.trim() !== "") yield parseMcpMessage(line);
+			newlineIndex = buffer.indexOf("\n");
+		}
+	}
+	if (buffer.trim() !== "") yield parseMcpMessage(buffer.trim());
+}
+function parseMcpMessage(payload) {
+	try {
+		return JSON.parse(payload);
+	} catch {
+		throw new BackgroundSessionMcpError("invalid MCP JSON payload");
+	}
+}
+function isJsonRpcRequestId(value) {
+	return value === null || typeof value === "string" || typeof value === "number";
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+//#endregion
+//#region src/bootstrap/mcp/rivus-mcp-entrypoint.ts
+async function runBackgroundSessionMcpServer(options = {}) {
+	const controlUrl = requireEnv("RIVUS_MCP_CONTROL_URL");
+	const controlToken = requireEnv("RIVUS_MCP_CONTROL_TOKEN");
+	const capability = requireEnv("RIVUS_MCP_CAPABILITY");
+	const enabledTools = optionalEnv("RIVUS_MCP_TOOLS")?.split(",").map((tool) => tool.trim()).filter(Boolean);
+	await createBackgroundSessionMcpServer({
+		capability,
+		controlToken,
+		controlUrl,
+		...enabledTools ? { enabledTools } : {},
+		...options.fetch ? { fetch: options.fetch } : {},
+		...options.input ? { input: options.input } : {},
+		...options.output ? { output: options.output } : {}
+	}).run();
+}
+function requireEnv(name) {
+	const value = process.env[name]?.trim();
+	if (!value) throw new BackgroundSessionMcpError(`${name} is required`);
+	return value;
+}
+function optionalEnv(name) {
+	return process.env[name]?.trim() || void 0;
+}
+//#endregion
+//#region src/core/application/background-session/control/background-session-control.ts
+function createBackgroundSessionControl$1(options) {
+	return { handle: async (command, context, input) => {
+		const executionContext = {
+			agentId: context.agentId,
+			callId: `mcp-call:${options.createId()}`,
+			instanceId: `mcp:${context.agentId}`,
+			policyEpoch: context.policyEpoch,
+			runId: context.runId,
+			sessionKey: context.sessionKey,
+			sourceMessageId: context.sourceMessageId,
+			toolId: `background.${command}`,
+			toolVersion: "1.0.0",
+			origin: toToolOrigin(context.origin)
+		};
+		switch (command) {
+			case "start": {
+				const { displayName, prompt } = readObject(input, ["displayName", "prompt"]);
+				if (typeof prompt !== "string" || prompt.trim() === "") throw new BackgroundSessionControlError("background.start requires a non-empty prompt");
+				const sessionId = `bg-${options.createId()}`;
+				return options.service.start({
+					authority: {
+						...context.authority,
+						sessionKey: createBackgroundSessionKey(sessionId)
+					},
+					context: executionContext,
+					...displayName === void 0 ? {} : { displayName: readString(displayName, "displayName") },
+					prompt,
+					sessionId
+				});
+			}
+			case "wait": return options.service.wait({
+				context: executionContext,
+				...readBackgroundSessionWaitInput(input, (message) => new BackgroundSessionControlError(message))
+			});
+			case "list": {
+				const { limit, phase } = readObject(input, ["limit", "phase"]);
+				return options.service.list({
+					context: executionContext,
+					...limit === void 0 ? {} : { limit: readInteger(limit, "limit") },
+					...phase === void 0 ? {} : { phase: readPhase(phase) }
+				});
+			}
+			case "status": {
+				const { sessionId } = readObject(input, ["sessionId"]);
+				return options.service.status({
+					context: executionContext,
+					sessionId: readString(sessionId, "sessionId")
+				});
+			}
+			case "send": {
+				const { message, sessionId } = readObject(input, ["message", "sessionId"]);
+				return options.service.send({
+					context: executionContext,
+					message: readString(message, "message"),
+					sessionId: readString(sessionId, "sessionId")
+				});
+			}
+			case "stop": {
+				const { reason, sessionId } = readObject(input, ["reason", "sessionId"]);
+				return options.service.stop({
+					context: executionContext,
+					...reason === void 0 ? {} : { reason: readString(reason, "reason") },
+					sessionId: readString(sessionId, "sessionId")
+				});
+			}
+		}
+	} };
+}
+var BackgroundSessionControlError = class extends Error {
+	name = "BackgroundSessionControlError";
+};
+function toControlContext$1(input) {
+	return {
+		agentId: input.agentId,
+		authority: input.authority,
+		origin: {
+			allowedActorOpenIds: input.origin.allowedActorOpenIds,
+			...input.origin.conversationId === void 0 ? {} : { conversationId: input.origin.conversationId },
+			endpointId: input.origin.endpointId,
+			tenantKey: input.origin.tenantKey
+		},
+		policyEpoch: input.policyEpoch,
+		runId: `mcp:${input.createId()}`,
+		sessionKey: input.sessionKey,
+		sourceMessageId: input.sourceMessageId ?? `mcp:${input.createId()}`
+	};
+}
+function toToolOrigin(origin) {
+	return {
+		allowedActorOpenIds: origin.allowedActorOpenIds,
+		endpointId: origin.endpointId,
+		tenantKey: origin.tenantKey,
+		...origin.conversationId === void 0 ? {} : { conversationId: origin.conversationId }
+	};
+}
+function readObject(input, allowed) {
+	return readBackgroundSessionObject(input, allowed, (message) => new BackgroundSessionControlError(message));
+}
+function readString(value, name) {
+	return readBackgroundSessionString(value, name, (message) => new BackgroundSessionControlError(message));
+}
+function readInteger(value, name) {
+	return readBackgroundSessionInteger(value, name, (message) => new BackgroundSessionControlError(message));
+}
+function readPhase(value) {
+	return readBackgroundSessionPhase(value, (message) => new BackgroundSessionControlError(message));
+}
+//#endregion
+//#region src/adapters/compatibility/background-session/control.ts
+function createBackgroundSessionControl(options) {
+	return createBackgroundSessionControl$1({
+		createId: createRandomId,
+		service: options.service
+	});
+}
+function toControlContext(input) {
+	return toControlContext$1({
+		...input,
+		createId: createRandomId
+	});
+}
+//#endregion
+//#region src/adapters/http/background-session/background-session-control-http-server.ts
+var BackgroundSessionControlHttpError = class extends Error {
+	statusCode;
+	name = "BackgroundSessionControlHttpError";
+	constructor(statusCode, message) {
+		super(message);
+		this.statusCode = statusCode;
+	}
+};
+const COMMANDS = [
+	"start",
+	"wait",
+	"list",
+	"status",
+	"send",
+	"stop"
+];
+function createBackgroundSessionControlHttpServer(options) {
+	let server;
+	let boundPort = options.port;
+	const capabilities = /* @__PURE__ */ new Map();
+	const capabilitiesBySessionKey = /* @__PURE__ */ new Map();
+	const serverHandle = createServer((request, response) => {
+		(async () => {
+			try {
+				if (request.method === "GET" && request.url === "/background-sessions/status") {
+					if (request.headers.authorization !== `Bearer ${options.token}`) throw new BackgroundSessionControlHttpError(401, "unauthorized");
+					respond(response, 200, {
+						ok: true,
+						result: options.status?.() ?? null
+					});
+					return;
+				}
+				if (request.method !== "POST" || request.url !== "/background-sessions") throw new BackgroundSessionControlHttpError(404, "not found");
+				if (request.headers.authorization !== `Bearer ${options.token}`) throw new BackgroundSessionControlHttpError(401, "unauthorized");
+				const envelope = parseEnvelope(await readBody(request, 64 * 1024));
+				const context = capabilities.get(envelope.capability);
+				if (!context) throw new BackgroundSessionControlHttpError(401, "unknown or expired capability");
+				const command = envelope.command;
+				if (!COMMANDS.includes(command)) throw new BackgroundSessionControlHttpError(400, `unsupported background session command: ${String(command)}`);
+				respond(response, 200, {
+					ok: true,
+					result: await options.control.handle(command, context, envelope.input)
+				});
+			} catch (error) {
+				respond(response, error instanceof BackgroundSessionControlHttpError ? error.statusCode : 500, {
+					error: {
+						message: error instanceof Error ? error.message : String(error),
+						name: error instanceof Error ? error.name : "Error"
+					},
+					ok: false
+				});
+			}
+		})();
+	});
+	serverHandle.on("error", () => void 0);
+	return {
+		port: () => boundPort,
+		close: async () => {
+			const active = server;
+			server = void 0;
+			capabilities.clear();
+			capabilitiesBySessionKey.clear();
+			if (active) await new Promise((resolve) => active.close(() => resolve()));
+		},
+		issueCapability: (context) => {
+			const existing = capabilitiesBySessionKey.get(context.sessionKey);
+			if (existing) return existing;
+			const capability = randomUUID();
+			capabilities.set(capability, context);
+			capabilitiesBySessionKey.set(context.sessionKey, capability);
+			return capability;
+		},
+		start: async () => {
+			if (server) return;
+			await new Promise((resolve, reject) => {
+				server = serverHandle;
+				serverHandle.listen(options.port, options.host ?? "127.0.0.1", () => {
+					const address = serverHandle.address();
+					if (address !== null && typeof address === "object") boundPort = address.port;
+					resolve();
+				});
+				serverHandle.once("error", (error) => {
+					server = void 0;
+					reject(error);
+				});
+			});
+		}
+	};
+}
+function respond(response, statusCode, body) {
+	response.writeHead(statusCode, { "content-type": "application/json" });
+	response.end(JSON.stringify(body));
+}
+function parseEnvelope(body) {
+	const parsed = JSON.parse(body);
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new BackgroundSessionControlHttpError(400, "invalid background session control envelope");
+	const record = parsed;
+	if (typeof record.command !== "string" || typeof record.capability !== "string") throw new BackgroundSessionControlHttpError(400, "background session control envelope requires command and capability");
+	return {
+		capability: record.capability,
+		command: record.command,
+		input: record.input
+	};
+}
+function readBody(request, maxBytes) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let total = 0;
+		request.on("data", (chunk) => {
+			total += chunk.length;
+			if (total > maxBytes) {
+				reject(new BackgroundSessionControlHttpError(413, "background session control request too large"));
+				return;
+			}
+			chunks.push(chunk);
+		});
+		request.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+	});
+}
+//#endregion
+//#region src/mcp.ts
+if (pathToFileURL(process.argv[1] ?? "").href === import.meta.url) await runBackgroundSessionMcpServer();
+//#endregion
+export { BACKGROUND_SESSION_MCP_SERVER_NAME, BACKGROUND_SESSION_MCP_SERVER_VERSION, BackgroundSessionControlError, BackgroundSessionControlHttpError, BackgroundSessionMcpError, createBackgroundSessionControl, createBackgroundSessionControlHttpServer, createBackgroundSessionMcpServer, runBackgroundSessionMcpServer, toControlContext };

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@rivus/gateway",
+  "version": "0.16.2",
+  "description": "Message gateway, channels, host binding, automation, and daemon assembly for Rivus.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": "^24.11.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PerfectPan/rivus-agent.git",
+    "directory": "packages/gateway"
+  },
+  "homepage": "https://github.com/PerfectPan/rivus-agent#readme",
+  "bugs": {
+    "url": "https://github.com/PerfectPan/rivus-agent/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js",
+      "default": "./dist/mcp.js"
+    },
+    "./bootstrap/pi-feishu": {
+      "types": "./dist/bootstrap/pi-feishu.d.ts",
+      "import": "./dist/bootstrap/pi-feishu.js",
+      "default": "./dist/bootstrap/pi-feishu.js"
+    },
+    "./cli": "./dist/cli.js",
+    "./plugin/starter": "./templates/rivus-starter.plugin.mjs",
+    "./skills/runtime-management/SKILL.md": "./skills/runtime-management/SKILL.md",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "templates/*.mjs",
+    "templates/*.bootstrap.ts",
+    "templates/*.json",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/generate-gateway-release-descriptor.mjs && vp pack",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vp test --run"
+  },
+  "dependencies": {
+    "@rivus/platform": "0.16.2",
+    "@rivus/runtime": "0.16.2",
+    "@larksuiteoapi/node-sdk": "1.71.1",
+    "axios": "1.18.0",
+    "effect": "^3.21.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/runtime-management/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: runtime-management
+description: Use when the user asks what model is active, requests a persistent model change, or asks to restore the previous model; invoke the installed Rivus CLI and report the returned status.
+---
+
+# Runtime management
+
+Use the installed `rivus` executable for the personal Home's model management. The CLI is the source of truth for the
+current revision and the durable request status. It validates an exact `provider/model` submitted by the Host; it does
+not enumerate the supported model catalog. Use a model identifier already confirmed by the Home configuration,
+deployment, the provider's official documentation, or a trusted Host response. Do not guess aliases or infer an
+identifier from a model family name. When the identifier remains ambiguous, ask the user for the exact value; the Host
+performs the final validation before accepting it.
+
+## Query
+
+Run:
+
+```bash
+rivus model status --json
+```
+
+Read `current`, `source`, `revision`, and `pending` from the JSON response. If a request is in progress, keep its
+`requestId` and `reason` visible to the user. Query a known request with:
+
+```bash
+rivus model status --request <request-id> --json
+```
+
+## Set a default model
+
+The default is shared by every Agent in the current Home, including their background Sessions. Describe that scope when
+submitting a change. If the user asks to change only one Agent, explain that per-Agent overrides are unsupported and
+resolve the requested scope before submitting a Home-wide change.
+
+Use the exact `provider/model` value confirmed by the Host. First obtain the current `revision`, then submit one request
+with a fresh request id:
+
+```bash
+rivus model set --model <provider/model> --expected-revision <revision> --request <request-id> --json
+```
+
+The first response confirms receipt. When the response is `pending`, report its `requestId` and finish the current Run.
+The Host completes validation and activation across the safe boundary and sends the final notification. A later Run can
+query the request to determine whether the final state is `applied`, `failed`, `restored`, or `recovery-required`.
+Keep the same request id after a disconnect instead of submitting the change again with a new id.
+
+## Restore the previous model
+
+Use the same revision and request rules:
+
+```bash
+rivus model rollback --expected-revision <revision> --request <request-id> --json
+```
+
+If there is no previous selection, or the provider no longer supports it, report the returned limitation. Restoring a
+model does not undo messages, memory, or completed business effects.
+
+## Trust and scope
+
+Only a trusted Host Run can authorize `set` and `rollback`. A local client without that context can read diagnostics but
+cannot grant itself permission. Do not add identity, owner, Home, credential, or authorization fields to a command.
+
+When a command reports `failed` or `recovery-required`, preserve the returned error code and request id. Do not infer
+success from process exit code `0`; inspect the JSON business status.