@rivus/agent 0.8.6 → 0.10.0

package/dist/acp.d.ts

@@ -77,6 +77,23 @@ interface AcpAgentServerOptions {
 declare function createAcpAgentServer(options: AcpAgentServerOptions): acp.AgentApp;
 declare function serveAcpAgentOnStdio(app: acp.AgentApp): Promise<void>;
 //#endregion
+//#region src/infrastructure/acp/acp-session-store.d.ts
+interface AcpSessionRecord {
+  readonly sessionId: string;
+}
+interface AcpSessionStore {
+  load(sessionKey: string): Promise<AcpSessionRecord | undefined>;
+  save(sessionKey: string, record: AcpSessionRecord): Promise<void>;
+}
+interface JsonAcpSessionStoreOptions {
+  readonly filePath: string;
+}
+/**
+ * A small deployment-owned store for ACP provider session identities.
+ * The file contains no prompts or credentials, only session-key bindings.
+ */
+declare function createJsonAcpSessionStore(options: JsonAcpSessionStoreOptions): AcpSessionStore;
+//#endregion
 //#region src/infrastructure/acp/acp-stdio-agent-loop.d.ts
 interface AcpMcpServerEnvironmentVariable {
   readonly name: string;
@@ -97,6 +114,8 @@ interface AcpStdioAgentLoopOptions {
   readonly mcpServers?: (input: AgentLoopInput) => ReadonlyArray<AcpMcpServer>;
   readonly onStderr?: (text: string) => void;
   readonly permissionPolicy?: AcpSessionPermissionPolicy;
+  /** Persist provider session IDs so a restarted ACP child can load/resume them. */
+  readonly sessionStore?: AcpSessionStore;
   readonly terminationTimeoutMs?: number;
   readonly workingDirectory: string;
 }
@@ -105,5 +124,16 @@ interface AcpStdioAgentLoopHandle {
   dispose(): Promise<void>;
 }
 declare function createAcpStdioAgentLoop(options: AcpStdioAgentLoopOptions): AcpStdioAgentLoopHandle;
+declare class AcpSessionResumeUnavailable extends Error {
+  readonly sessionId: string;
+  readonly name = "AcpSessionResumeUnavailable";
+  constructor(sessionId: string);
+}
+declare class AcpSessionResumeFailed extends Error {
+  readonly sessionId: string;
+  readonly cause: unknown;
+  readonly name = "AcpSessionResumeFailed";
+  constructor(sessionId: string, cause: unknown);
+}
 //#endregion
-export { type AcpAgentLoopOptions, type AcpAgentServerOptions, type AcpAgentSession, type AcpPermissionBridge, type AcpPermissionDecision, type AcpPermissionOption, type AcpPermissionPolicy, type AcpPermissionRequest, type AcpPermissionSelection, type AcpPermissionToolCall, type AcpPromptResult, type AcpSessionPermissionContext, type AcpSessionPermissionPolicy, type AcpSessionUpdate, type AcpStdioAgentLoopHandle, type AcpStdioAgentLoopOptions, type AcpToolCallStatus, createAcpAgentLoop, createAcpAgentServer, createAcpPermissionBridge, createAcpStdioAgentLoop, decideAcpPermission, serveAcpAgentOnStdio };
+export { type AcpAgentLoopOptions, type AcpAgentServerOptions, type AcpAgentSession, type AcpPermissionBridge, type AcpPermissionDecision, type AcpPermissionOption, type AcpPermissionPolicy, type AcpPermissionRequest, type AcpPermissionSelection, type AcpPermissionToolCall, type AcpPromptResult, type AcpSessionPermissionContext, type AcpSessionPermissionPolicy, type AcpSessionRecord, AcpSessionResumeFailed, AcpSessionResumeUnavailable, type AcpSessionStore, type AcpSessionUpdate, type AcpStdioAgentLoopHandle, type AcpStdioAgentLoopOptions, type AcpToolCallStatus, type JsonAcpSessionStoreOptions, createAcpAgentLoop, createAcpAgentServer, createAcpPermissionBridge, createAcpStdioAgentLoop, createJsonAcpSessionStore, decideAcpPermission, serveAcpAgentOnStdio };

package/dist/acp.js

@@ -4,6 +4,8 @@ import { randomUUID } from "node:crypto";
 import { Readable, Writable } from "node:stream";
 import * as acp from "@agentclientprotocol/sdk";
 import { spawn } from "node:child_process";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
 //#region src/infrastructure/acp/acp-agent-loop.ts
 function createAcpAgentLoop(options) {
 	return createAsyncIterableAgentLoop({ run: (input) => runAcpSession(input, options) });
@@ -109,10 +111,10 @@ function mapAcpSessionUpdate(update, tools) {
 	})];
 }
 function readTextContent(content) {
-	if (!isRecord(content) || content.type !== "text" || typeof content.text !== "string") return void 0;
+	if (!isRecord$1(content) || content.type !== "text" || typeof content.text !== "string") return void 0;
 	return content.text;
 }
-function isRecord(value) {
+function isRecord$1(value) {
 	return typeof value === "object" && value !== null;
 }
 //#endregion
@@ -252,17 +254,48 @@ 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({
+	const mcpServers = createMcpServers(options, input);
+	const persisted = await options.sessionStore?.load(input.sessionKey);
+	if (persisted) return restoreAcpSession(processConnection, options, persisted.sessionId, mcpServers);
+	const session = await processConnection.connection.agent.buildSession({
+		cwd: options.workingDirectory,
+		mcpServers
+	}).start();
+	await options.sessionStore?.save(input.sessionKey, { sessionId: session.sessionId });
+	return session;
+}
+function createMcpServers(options, input) {
+	return (options.mcpServers?.(input) ?? []).map((server) => ({
 		args: [...server.args],
 		command: server.command,
 		env: server.env.map(({ name, value }) => ({
 			name,
 			value
 		})),
-		name: server.name
-	});
-	return builder.start();
+		name: server.name,
+		type: "stdio"
+	}));
+}
+async function restoreAcpSession(processConnection, options, sessionId, mcpServers) {
+	const session = new ResumedAcpSession(processConnection, sessionId);
+	try {
+		if (processConnection.agentCapabilities?.loadSession) await processConnection.connection.agent.request(acp.methods.agent.session.load, {
+			cwd: options.workingDirectory,
+			mcpServers,
+			sessionId
+		});
+		else if (processConnection.agentCapabilities?.sessionCapabilities?.resume) await processConnection.connection.agent.request(acp.methods.agent.session.resume, {
+			cwd: options.workingDirectory,
+			mcpServers,
+			sessionId
+		});
+		else throw new AcpSessionResumeUnavailable(sessionId);
+		session.clearReplay();
+		return session;
+	} catch (error) {
+		session.dispose();
+		throw new AcpSessionResumeFailed(sessionId, error);
+	}
 }
 function createAcpStdioAgentLoop(options) {
 	let pendingConnection;
@@ -291,6 +324,7 @@ function createAcpStdioAgentLoop(options) {
 				sessionKeys.clear();
 				for (const session of processConnection.sessions.values()) session.dispose();
 				processConnection.sessions.clear();
+				processConnection.sessionUpdateHandlers.clear();
 				terminateChild(processConnection.child, options.terminationTimeoutMs);
 			});
 		}, () => {
@@ -312,6 +346,7 @@ function createAcpStdioAgentLoop(options) {
 			if (processConnection) {
 				for (const session of processConnection.sessions.values()) session.dispose();
 				processConnection.sessions.clear();
+				processConnection.sessionUpdateHandlers.clear();
 				processConnection.connection.close();
 			}
 			sessionKeys.clear();
@@ -330,7 +365,7 @@ function createAcpStdioAgentLoop(options) {
 					current.dispose();
 					processConnection.sessions.delete(input.sessionKey);
 				}
-				const session = new SdkAcpAgentSession(await buildAcpSession(processConnection, options, input), processConnection.connection.agent);
+				const session = new SdkAcpAgentSession(await buildAcpSession(processConnection, options, input), processConnection.connection.agent, options.sessionStore !== void 0);
 				sessionKeys.set(session.sessionId, input.sessionKey);
 				processConnection.sessions.set(input.sessionKey, session);
 				return session;
@@ -341,10 +376,12 @@ function createAcpStdioAgentLoop(options) {
 var SdkAcpAgentSession = class {
 	session;
 	agent;
+	preserveOnCancel;
 	reusable = true;
-	constructor(session, agent) {
+	constructor(session, agent, preserveOnCancel) {
 		this.session = session;
 		this.agent = agent;
+		this.preserveOnCancel = preserveOnCancel;
 	}
 	get sessionId() {
 		return this.session.sessionId;
@@ -353,7 +390,7 @@ var SdkAcpAgentSession = class {
 		return this.reusable;
 	}
 	cancel() {
-		this.reusable = false;
+		if (!this.preserveOnCancel) this.reusable = false;
 		return this.agent.notify(acp.methods.agent.session.cancel, { sessionId: this.session.sessionId });
 	}
 	dispose() {
@@ -369,6 +406,88 @@ var SdkAcpAgentSession = class {
 		}
 	}
 };
+var ResumedAcpSession = class {
+	processConnection;
+	sessionId;
+	updates = [];
+	waiters = [];
+	disposed = false;
+	failure;
+	constructor(processConnection, sessionId) {
+		this.processConnection = processConnection;
+		this.sessionId = sessionId;
+		processConnection.sessionUpdateHandlers.set(sessionId, (notification) => {
+			this.enqueue({
+				kind: "session_update",
+				update: notification.update
+			});
+		});
+	}
+	clearReplay() {
+		this.updates.splice(0);
+	}
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.processConnection.sessionUpdateHandlers.delete(this.sessionId);
+		const error = /* @__PURE__ */ new Error(`ACP session ${this.sessionId} observer disposed`);
+		for (const waiter of this.waiters.splice(0)) waiter.reject(error);
+		this.updates.splice(0);
+	}
+	nextUpdate() {
+		if (this.updates.length > 0) return Promise.resolve(this.updates.shift());
+		if (this.failure !== void 0) return Promise.reject(this.failure);
+		if (this.disposed) return Promise.reject(/* @__PURE__ */ new Error(`ACP session ${this.sessionId} observer disposed`));
+		return new Promise((resolve, reject) => this.waiters.push({
+			reject,
+			resolve
+		}));
+	}
+	prompt(text) {
+		if (this.disposed) return Promise.reject(/* @__PURE__ */ new Error(`ACP session ${this.sessionId} observer disposed`));
+		const response = this.processConnection.connection.agent.request(acp.methods.agent.session.prompt, {
+			prompt: [{
+				text,
+				type: "text"
+			}],
+			sessionId: this.sessionId
+		});
+		response.then((result) => this.enqueue({
+			kind: "stop",
+			stopReason: result.stopReason
+		}), (error) => this.fail(error));
+		return response;
+	}
+	enqueue(message) {
+		if (this.disposed) return;
+		const waiter = this.waiters.shift();
+		if (waiter) waiter.resolve(message);
+		else this.updates.push(message);
+	}
+	fail(error) {
+		if (this.failure !== void 0 || this.disposed) return;
+		this.failure = error;
+		for (const waiter of this.waiters.splice(0)) waiter.reject(error);
+	}
+};
+var AcpSessionResumeUnavailable = class extends Error {
+	sessionId;
+	name = "AcpSessionResumeUnavailable";
+	constructor(sessionId) {
+		super(`ACP Agent cannot load or resume persisted session ${sessionId}`);
+		this.sessionId = sessionId;
+	}
+};
+var AcpSessionResumeFailed = class extends Error {
+	sessionId;
+	cause;
+	name = "AcpSessionResumeFailed";
+	constructor(sessionId, cause) {
+		super(`ACP Agent failed to restore persisted session ${sessionId}`);
+		this.sessionId = sessionId;
+		this.cause = cause;
+	}
+};
 async function openConnection(options, sessionKeys, onSpawn) {
 	const child = spawn(options.command, [...options.arguments ?? []], {
 		cwd: options.workingDirectory,
@@ -383,9 +502,12 @@ async function openConnection(options, sessionKeys, onSpawn) {
 	child.stderr.setEncoding("utf8");
 	if (options.onStderr) child.stderr.on("data", options.onStderr);
 	else child.stderr.resume();
+	const sessionUpdateHandlers = /* @__PURE__ */ new Map();
 	const app = acp.client({ name: options.clientName ?? "rivus" }).onRequest(acp.methods.client.session.requestPermission, async ({ params }) => {
 		const sessionKey = sessionKeys.get(params.sessionId);
 		return { outcome: await decideAcpPermission(toPermissionRequest(params), sessionKey && options.permissionPolicy ? (request) => options.permissionPolicy?.(request, { sessionKey }) : void 0) };
+	}).onNotification(acp.methods.client.session.update, ({ params }) => {
+		sessionUpdateHandlers.get(params.sessionId)?.(params);
 	});
 	const stream = acp.ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
 	const connection = app.connect(stream);
@@ -400,8 +522,10 @@ async function openConnection(options, sessionKeys, onSpawn) {
 		}), options.initializationTimeoutMs ?? 1e4, "ACP initialization timed out");
 		if (initialized.protocolVersion !== acp.PROTOCOL_VERSION) throw new Error(`ACP protocol version ${initialized.protocolVersion} is not supported`);
 		return {
+			...initialized.agentCapabilities ? { agentCapabilities: initialized.agentCapabilities } : {},
 			child,
 			connection,
+			sessionUpdateHandlers,
 			sessions: /* @__PURE__ */ new Map()
 		};
 	} catch (error) {
@@ -456,4 +580,57 @@ function withTimeout(promise, timeoutMs, message) {
 	});
 }
 //#endregion
-export { createAcpAgentLoop, createAcpAgentServer, createAcpPermissionBridge, createAcpStdioAgentLoop, decideAcpPermission, serveAcpAgentOnStdio };
+//#region src/infrastructure/acp/acp-session-store.ts
+/**
+* A small deployment-owned store for ACP provider session identities.
+* The file contains no prompts or credentials, only session-key bindings.
+*/
+function createJsonAcpSessionStore(options) {
+	let recordsPromise;
+	let writeChain = Promise.resolve();
+	const readRecords = async () => {
+		try {
+			const raw = await readFile(options.filePath, "utf8");
+			const parsed = JSON.parse(raw);
+			if (!isRecord(parsed)) throw new Error("ACP session store must contain an object");
+			const records = /* @__PURE__ */ new Map();
+			for (const [sessionKey, value] of Object.entries(parsed)) {
+				if (!isRecord(value) || typeof value.sessionId !== "string" || value.sessionId.trim() === "") throw new Error(`invalid ACP session record for ${sessionKey}`);
+				records.set(sessionKey, { sessionId: value.sessionId });
+			}
+			return records;
+		} catch (error) {
+			if (isMissingFile(error)) return /* @__PURE__ */ new Map();
+			throw error;
+		}
+	};
+	const records = async () => {
+		recordsPromise ??= readRecords();
+		return recordsPromise;
+	};
+	const persist = async (value) => {
+		const temporaryPath = `${options.filePath}.tmp-${process.pid}-${Date.now()}`;
+		await mkdir(dirname(options.filePath), { recursive: true });
+		await writeFile(temporaryPath, `${JSON.stringify(Object.fromEntries(value), null, 2)}\n`, "utf8");
+		await rename(temporaryPath, options.filePath);
+	};
+	return {
+		load: async (sessionKey) => (await records()).get(sessionKey),
+		save: async (sessionKey, record) => {
+			writeChain = writeChain.then(async () => {
+				const current = await records();
+				current.set(sessionKey, { sessionId: record.sessionId });
+				await persist(current);
+			});
+			await writeChain;
+		}
+	};
+}
+function isMissingFile(error) {
+	return isRecord(error) && error.code === "ENOENT";
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+//#endregion
+export { AcpSessionResumeFailed, AcpSessionResumeUnavailable, createAcpAgentLoop, createAcpAgentServer, createAcpPermissionBridge, createAcpStdioAgentLoop, createJsonAcpSessionStore, decideAcpPermission, serveAcpAgentOnStdio };

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 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";
 import { lstat, mkdir, readFile, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 //#region src/infrastructure/project/rivus-project-doctor.ts
 const REQUIRED_FILES = Object.freeze([
 	"package.json",

package/dist/index.js

@@ -8,8 +8,8 @@ import { a as readBackgroundSessionWaitInput, i as readBackgroundSessionString,
 import { n as assertRivusPluginConforms, r as createFakeRivusPlugin, t as RivusPluginConformanceError } from "./rivus-plugin-testkit.js";
 import { Cause, Deferred, Effect, Either, Exit, Fiber, Option, Stream } from "effect";
 import { createHash, randomUUID } from "node:crypto";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { appendFile, lstat, mkdir, readFile, readdir, realpath, rename, stat, truncate, unlink, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { createServer } from "node:http";
 import { Buffer as Buffer$1 } from "node:buffer";

package/dist/mcp.d.ts

@@ -40,7 +40,7 @@ declare function toControlContext(input: {
 declare const BACKGROUND_SESSION_MCP_SERVER_NAME = "rivus-background-sessions";
 declare const BACKGROUND_SESSION_MCP_SERVER_VERSION = "1.0.0";
 interface BackgroundSessionMcpServerOptions {
-  readonly controlContext: BackgroundSessionControlContext;
+  readonly capability: string;
   readonly controlUrl: string;
   readonly controlToken: string;
   readonly enabledTools?: ReadonlyArray<BackgroundSessionControlCommand>;
@@ -74,6 +74,7 @@ interface BackgroundSessionControlHttpServerOptions {
 }
 interface BackgroundSessionControlHttpServer {
   port(): number;
+  issueCapability(context: BackgroundSessionControlContext): string;
   close(): Promise<void>;
   start(): Promise<void>;
 }

package/dist/mcp.js

@@ -24,15 +24,14 @@ function createBackgroundSessionMcpServer(options) {
 	const tools = createBackgroundSessionToolContracts().filter(({ id }) => enabledTools.has(id.slice(11))).map((contract) => ({
 		description: contract.description,
 		inputSchema: contract.inputSchema,
-		name: contract.id,
-		outputSchema: { type: "object" }
+		name: contract.id
 	}));
 	const serverInfo = {
 		name: options.serverName ?? "rivus-background-sessions",
 		version: options.serverVersion ?? "1.0.0"
 	};
 	return { run: () => runMcpServer({
-		controlContext: options.controlContext,
+		capability: options.capability,
 		controlToken: options.controlToken,
 		controlUrl: options.controlUrl,
 		fetchImplementation,
@@ -45,10 +44,10 @@ function createBackgroundSessionMcpServer(options) {
 async function runBackgroundSessionMcpServer(options = {}) {
 	const controlUrl = requireEnv("RIVUS_MCP_CONTROL_URL");
 	const controlToken = requireEnv("RIVUS_MCP_CONTROL_TOKEN");
-	const context = parseContext(requireEnv("RIVUS_MCP_CONTEXT"));
+	const capability = requireEnv("RIVUS_MCP_CAPABILITY");
 	const enabledTools = optionalEnv("RIVUS_MCP_TOOLS")?.split(",").map((tool) => tool.trim()).filter(Boolean);
 	await createBackgroundSessionMcpServer({
-		controlContext: context,
+		capability,
 		controlToken,
 		controlUrl,
 		...enabledTools ? { enabledTools } : {},
@@ -60,16 +59,17 @@ async function runBackgroundSessionMcpServer(options = {}) {
 async function runMcpServer(options) {
 	const send = (message) => {
 		const body = JSON.stringify(message);
-		options.output.write(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+		options.output.write(`${body}\n`);
 	};
 	for await (const message of readMcpMessages(options.input)) {
-		if (!isRecord(message) || typeof message.id !== "number") continue;
+		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 } },
@@ -80,12 +80,14 @@ async function runMcpServer(options) {
 					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 }
 					});
@@ -96,6 +98,7 @@ async function runMcpServer(options) {
 					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,
@@ -106,8 +109,8 @@ async function runMcpServer(options) {
 					}
 					const response = await options.fetchImplementation(options.controlUrl, {
 						body: JSON.stringify({
+							capability: options.capability,
 							command,
-							context: options.controlContext,
 							input: params.arguments ?? {}
 						}),
 						headers: {
@@ -120,6 +123,7 @@ async function runMcpServer(options) {
 					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,
@@ -129,6 +133,7 @@ async function runMcpServer(options) {
 						break;
 					}
 					send({
+						jsonrpc: "2.0",
 						id: message.id,
 						result: {
 							content: [{
@@ -141,6 +146,7 @@ async function runMcpServer(options) {
 					break;
 				}
 				default: send({
+					jsonrpc: "2.0",
 					id: message.id,
 					error: {
 						code: -32601,
@@ -150,6 +156,7 @@ async function runMcpServer(options) {
 			}
 		} catch (error) {
 			send({
+				jsonrpc: "2.0",
 				id: message.id,
 				error: {
 					code: -32e3,
@@ -163,36 +170,25 @@ async function* readMcpMessages(input) {
 	let buffer = "";
 	for await (const chunk of input) {
 		buffer += chunk.toString("utf8");
-		let parsed = parseNextMessage(buffer);
-		while (parsed) {
-			yield parsed.message;
-			buffer = Buffer.from(buffer).subarray(parsed.byteLength).toString("utf8");
-			parsed = parseNextMessage(buffer);
+		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 parseNextMessage(buffer) {
-	const headerEnd = buffer.indexOf("\r\n\r\n");
-	if (headerEnd < 0) return void 0;
-	const contentLength = buffer.slice(0, headerEnd).split("\r\n").find((header) => /^Content-Length:\s*\d+$/i.test(header));
-	if (!contentLength) throw new BackgroundSessionMcpError("MCP message is missing a Content-Length header");
-	const byteLength = Number(contentLength.slice(15).trim());
-	const headerBytes = Buffer.byteLength(buffer.slice(0, headerEnd + 4));
-	if (Buffer.byteLength(buffer) < headerBytes + byteLength) return void 0;
-	const payload = Buffer.from(buffer).subarray(headerBytes, headerBytes + byteLength).toString("utf8");
+function parseMcpMessage(payload) {
 	try {
-		return {
-			byteLength: headerBytes + byteLength,
-			message: JSON.parse(payload)
-		};
+		return JSON.parse(payload);
 	} catch {
 		throw new BackgroundSessionMcpError("invalid MCP JSON payload");
 	}
 }
-function parseContext(value) {
-	const parsed = JSON.parse(value);
-	if (!isRecord(parsed)) throw new BackgroundSessionMcpError("RIVUS_MCP_CONTEXT must be a JSON object");
-	return parsed;
+function isJsonRpcRequestId(value) {
+	return value === null || typeof value === "string" || typeof value === "number";
 }
 function requireEnv(name) {
 	const value = process.env[name]?.trim();
@@ -335,6 +331,8 @@ const COMMANDS = [
 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 {
@@ -349,11 +347,13 @@ function createBackgroundSessionControlHttpServer(options) {
 				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, envelope.context, envelope.input)
+					result: await options.control.handle(command, context, envelope.input)
 				});
 			} catch (error) {
 				respond(response, error instanceof BackgroundSessionControlHttpError ? error.statusCode : 500, {
@@ -372,8 +372,18 @@ function createBackgroundSessionControlHttpServer(options) {
 		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) => {
@@ -399,10 +409,10 @@ 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" || record.context === void 0) throw new BackgroundSessionControlHttpError(400, "background session control envelope requires command and context");
+	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,
-		context: record.context,
 		input: record.input
 	};
 }

package/dist/pi.js

@@ -1,8 +1,8 @@
 import { d as requiresToolApproval } from "./agent-memory.js";
 import { l as createPiSkillRuntime, o as createInvocationAuthority, r as createToolInputDigest } from "./tool-input-digest.js";
 import { createHash } from "node:crypto";
-import { isAbsolute, relative } from "node:path";
 import { readFile, realpath, stat } from "node:fs/promises";
+import { isAbsolute, relative } from "node:path";
 import { Unsafe } from "typebox";
 import { createReadToolDefinition } from "@earendil-works/pi-coding-agent";
 //#region src/infrastructure/pi/pi-project-skill-read-tool.ts

package/dist/rivus-daemon-cli.js

@@ -4,9 +4,9 @@ import { n as resolveRivusAgentDefinition, r as deepFreeze, t as createRivusPlug
 import { createRequire } from "node:module";
 import { Effect } from "effect";
 import { createHash, randomUUID } from "node:crypto";
-import { pathToFileURL } from "node:url";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { lstat, open, readFile, readdir, realpath, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
 import { constants } from "node:fs";
 //#region src/application/plugin/rivus-automation-runtime-definition.ts
 function resolveRivusAutomationRuntimeDefinition(definition, requestedToolIds, requestedSkillIds) {

package/examples/acp-stdio-proxy.mjs

@@ -4,6 +4,7 @@ import {
   createAcpAgentServer,
   createAcpPermissionBridge,
   createAcpStdioAgentLoop,
+  createJsonAcpSessionStore,
   serveAcpAgentOnStdio
 } from "@rivus/agent/acp";
 
@@ -11,6 +12,7 @@ const command = process.env.RIVUS_ACP_SERVER_COMMAND?.trim();
 if (!command) throw new Error("RIVUS_ACP_SERVER_COMMAND is required and must resolve to an explicit executable");
 
 const workingDirectory = process.env.RIVUS_ACP_WORKING_DIRECTORY?.trim() || process.cwd();
+const sessionStorePath = process.env.RIVUS_ACP_SESSION_STORE?.trim();
 const permissionBridge = createAcpPermissionBridge();
 const downstream = createAcpStdioAgentLoop({
   arguments: parseArguments(process.env.RIVUS_ACP_SERVER_ARGUMENTS),
@@ -18,6 +20,7 @@ const downstream = createAcpStdioAgentLoop({
   environment: selectEnvironment(process.env.RIVUS_ACP_SERVER_ENV_KEYS),
   onStderr: (text) => process.stderr.write(text),
   permissionPolicy: permissionBridge.policy,
+  ...(sessionStorePath ? { sessionStore: createJsonAcpSessionStore({ filePath: sessionStorePath }) } : {}),
   workingDirectory
 });
 const server = createAcpAgentServer({

package/package.json

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