@rivus/agent 0.3.1 → 0.4.1

package/README.md

@@ -14,7 +14,7 @@ The first milestone is intentionally narrow: make the agent loop and agent harne
 - Host-issued invocation authority and a call-time Tool Broker that checks exact grants, pinned versions, online revocation, stable operation IDs, durable side-effect fencing, and one-time approval receipts bound to canonical input digests. The Pi Tool Proxy and Feishu Human Interaction gateway are wired in the deployment example.
 - 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/audience identity, and a provider-neutral `rivus_memory` Tool wired into the Pi manifest Runtime. Agent-private proposals survive process replacement; group invocations fail closed to their current Conversation scope, and Shared Profile reads expose only confirmed records. Automatic Recall, durable confirmation UX, typed Shared Profile fields, full provenance/retention metadata, and durable Compaction are still separate work.
-- Manifest-driven daily Agent Automations with 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.
+- 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.
 - 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.
@@ -160,7 +160,7 @@ Endpoint factories receive a Host-bound `handle()` function. Inbound payload fie
 
 An Endpoint may opt into Feishu's native process message with `"experimental": { "cotMessages": true }`. The deployment then requires a local `RIVUS_FEISHU_COT_BASE_URL`; no environment-specific origin is committed or inferred. Rivus creates the process message before the CardKit target so Feishu displays the process above the authoritative final answer, then renders redacted reasoning, model/Skill steps, and Tool calls into AG-UI COT events. Tool arguments remain valid redacted JSON as required by AG-UI, while the Feishu presenter uses narrow mappings for the deployment's known Tools, a sanitized bounded fallback for unknown Tools, and labeled result lines such as `查询天气 · 北京`. COT failures are reported and degrade to CardKit instead of failing the Agent Run; if CardKit preparation fails after COT creation, Rivus explicitly closes that process as failed.
 
-The example also declares a disabled `daily-ielts-word` Automation. Enable it only in a gitignored local manifest and set its `targetRef` variable to a Feishu receive ID. The current scheduler accepts the fixed-daily cron subset `M H * * *` plus an IANA time zone. Each occurrence uses an Automation-only Agent Instance and Session, persists generated text before delivery, and sends with a stable Feishu UUID so restart or delivery retry does not create another model answer. It is a local single-writer scheduler, not a distributed cron service.
+The example declares disabled `daily-ielts-word`, `a-share-pre-market`, and `a-share-post-market` Automations. Enable them only in a gitignored local manifest and set each `targetRef` variable to a Feishu receive ID. The scheduler accepts `M H * * *` and the weekday-only subset `M H * * 1-5` plus an IANA time zone. The A-share templates run at 09:00 and 16:00 on weekdays, request only the bounded evidence-backed briefing Tool, and relay its source-attributed facts and explicitly labeled inferences without letting the model invent market numbers or causal claims; see the [A-share briefing runbook](docs/en/operations/a-share-market-briefing.md). Each occurrence uses an Automation-only Agent Instance and Session, persists generated text before delivery, and sends with a stable Feishu UUID so restart or delivery retry does not create another model answer. An endpoint-less worker Agent may deliver through another enabled Agent's Host-owned Endpoint, allowing one visible Feishu bot to present multiple isolated task Profiles without inheriting their Tool grants or state. It is a local single-writer scheduler, not a distributed cron service.
 
 ```bash
 rivus --env-file .env.local \
@@ -1059,7 +1059,7 @@ const bootstrap = await Effect.runPromise(
 );
 ```
 
-The configured preparation helper creates a blue streaming CardKit entity, replies to the inbound Feishu message, and binds the run to the card target before any stream action is published. The running card includes a “Stop generating” button carrying `{ rivus_action: "cancel_run", run_id, session_key }`; completed, failed, and cancelled cards remove it. The configured publisher coalesces consecutive `update_text` actions by run, flushes the latest text before a terminal action, and exposes `flush(runId?)` for explicit worker-driven flushing. `createConfiguredRivusDaemonBootstrap` adds the event log, history restore helper, status reporter, optional status transport, WebSocket transport, worker loop, and managed process around those same pieces; `restoreConfiguredRivusDaemonBootstrap` first replays that event log as restored harness events so read models and same-session loop input are hydrated after restart. Local tests can use `createInMemoryFeishuCardTargetRegistry`; daemon processes should prefer `createJsonFileFeishuCardTargetRegistry` so run-to-card bindings survive restarts and malformed registry files fail loudly instead of being treated as empty state.
+The configured preparation helper creates a blue streaming CardKit entity, replies to the inbound Feishu message, and binds the run to the card target before any stream action is published. The running card includes a “Stop generating” button carrying `{ rivus_action: "cancel_run", run_id, session_key }`; completed, failed, and cancelled cards remove it. The configured publisher coalesces consecutive `update_text` actions by run, flushes the latest text before a terminal action, and exposes `flush(runId?)` for explicit worker-driven flushing. `createConfiguredRivusDaemonBootstrap` flushes pending text at `config.feishu.streamMinIntervalMs` by default; pass `flushIntervalMs` only to override that cadence. It also adds the event log, history restore helper, status reporter, optional status transport, WebSocket transport, worker loop, and managed process around those same pieces; `restoreConfiguredRivusDaemonBootstrap` first replays that event log as restored harness events so read models and same-session loop input are hydrated after restart. Local tests can use `createInMemoryFeishuCardTargetRegistry`; daemon processes should prefer `createJsonFileFeishuCardTargetRegistry` so run-to-card bindings survive restarts and malformed registry files fail loudly instead of being treated as empty state.
 
 ## Design Notes
 

package/dist/acp.d.ts

@@ -0,0 +1,98 @@
+import { s as AgentLoopInput, t as AgentLoop } from "./agent-loop.js";
+import * as acp from "@agentclientprotocol/sdk";
+
+//#region src/infrastructure/acp/acp-agent-loop.d.ts
+type AcpToolCallStatus = "pending" | "in_progress" | "completed" | "failed";
+interface AcpSessionUpdate {
+  readonly content?: unknown;
+  readonly name?: string | null;
+  readonly rawInput?: unknown;
+  readonly rawOutput?: unknown;
+  readonly sessionUpdate: string;
+  readonly status?: AcpToolCallStatus | null;
+  readonly title?: string | null;
+  readonly toolCallId?: string;
+  readonly [key: string]: unknown;
+}
+interface AcpPromptResult {
+  readonly stopReason: string;
+}
+interface AcpAgentSession {
+  cancel(): Promise<void> | void;
+  prompt(text: string, onUpdate: (update: AcpSessionUpdate) => void): Promise<AcpPromptResult>;
+  dispose?(): Promise<void> | void;
+}
+interface AcpAgentLoopOptions {
+  readonly disposeSessionAfterRun?: boolean;
+  readonly resolveSession: (input: AgentLoopInput) => Promise<AcpAgentSession> | AcpAgentSession;
+}
+declare function createAcpAgentLoop(options: AcpAgentLoopOptions): AgentLoop;
+//#endregion
+//#region src/infrastructure/acp/acp-permission-policy.d.ts
+interface AcpPermissionOption {
+  readonly kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
+  readonly name: string;
+  readonly optionId: string;
+}
+interface AcpPermissionToolCall {
+  readonly toolCallId: string;
+  readonly title?: string;
+  readonly rawInput?: unknown;
+}
+interface AcpPermissionRequest {
+  readonly options: ReadonlyArray<AcpPermissionOption>;
+  readonly sessionId: string;
+  readonly toolCall: AcpPermissionToolCall;
+}
+interface AcpPermissionSelection {
+  readonly optionId: string;
+}
+type AcpPermissionDecision = {
+  readonly outcome: "cancelled";
+} | {
+  readonly optionId: string;
+  readonly outcome: "selected";
+};
+type AcpPermissionPolicy = (request: AcpPermissionRequest) => Promise<AcpPermissionSelection | undefined> | AcpPermissionSelection | undefined;
+interface AcpSessionPermissionContext {
+  readonly sessionKey: string;
+}
+type AcpSessionPermissionPolicy = (request: AcpPermissionRequest, context: AcpSessionPermissionContext) => Promise<AcpPermissionSelection | undefined> | AcpPermissionSelection | undefined;
+declare function decideAcpPermission(request: AcpPermissionRequest, policy?: AcpPermissionPolicy): Promise<AcpPermissionDecision>;
+//#endregion
+//#region src/infrastructure/acp/acp-permission-bridge.d.ts
+interface AcpPermissionBridge {
+  readonly policy: AcpSessionPermissionPolicy;
+  bind(sessionKey: string, policy: AcpPermissionPolicy): () => void;
+}
+declare function createAcpPermissionBridge(): AcpPermissionBridge;
+//#endregion
+//#region src/infrastructure/acp/acp-agent-server.d.ts
+interface AcpAgentServerOptions {
+  readonly agentName?: string;
+  readonly loop: AgentLoop;
+  readonly permissionBridge?: AcpPermissionBridge;
+  readonly workingDirectory: string;
+}
+declare function createAcpAgentServer(options: AcpAgentServerOptions): acp.AgentApp;
+declare function serveAcpAgentOnStdio(app: acp.AgentApp): Promise<void>;
+//#endregion
+//#region src/infrastructure/acp/acp-stdio-agent-loop.d.ts
+interface AcpStdioAgentLoopOptions {
+  readonly arguments?: ReadonlyArray<string>;
+  readonly clientName?: string;
+  readonly command: string;
+  readonly environment?: Readonly<Record<string, string>>;
+  readonly initializationTimeoutMs?: number;
+  readonly onStderr?: (text: string) => void;
+  readonly permissionPolicy?: AcpSessionPermissionPolicy;
+  readonly terminationTimeoutMs?: number;
+  readonly workingDirectory: string;
+}
+interface AcpStdioAgentLoopHandle {
+  readonly loop: AgentLoop;
+  dispose(): Promise<void>;
+}
+declare function createAcpStdioAgentLoop(options: AcpStdioAgentLoopOptions): AcpStdioAgentLoopHandle;
+//#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 };

package/dist/acp.js

@@ -0,0 +1,436 @@
+import { c as createAgentLoopToolExecutionEnd, d as createAsyncIterableAgentLoop, l as createAgentLoopToolExecutionStart, o as createAgentLoopTextDelta, s as createAgentLoopThinkingDelta, u as createAgentLoopToolExecutionUpdate } from "./agent-loop.js";
+import { Effect, Stream } from "effect";
+import { randomUUID } from "node:crypto";
+import { Readable, Writable } from "node:stream";
+import * as acp from "@agentclientprotocol/sdk";
+import { spawn } from "node:child_process";
+//#region src/infrastructure/acp/acp-agent-loop.ts
+function createAcpAgentLoop(options) {
+	return createAsyncIterableAgentLoop({ run: (input) => runAcpSession(input, options) });
+}
+async function* runAcpSession(input, options) {
+	const session = await options.resolveSession(input);
+	const updates = [];
+	const tools = /* @__PURE__ */ new Map();
+	let wake;
+	let completed = false;
+	let failure;
+	const onAbort = () => {
+		Promise.resolve(session.cancel()).catch((error) => {
+			failure = error;
+			completed = true;
+			wake?.();
+			wake = void 0;
+		});
+	};
+	input.abortSignal.addEventListener("abort", onAbort, { once: true });
+	const prompt = session.prompt(input.text, (update) => {
+		updates.push(...mapAcpSessionUpdate(update, tools));
+		wake?.();
+		wake = void 0;
+	}).catch((error) => {
+		if (!input.abortSignal.aborted) failure = error;
+	}).finally(() => {
+		completed = true;
+		wake?.();
+		wake = void 0;
+	});
+	try {
+		if (input.abortSignal.aborted) onAbort();
+		while (!completed || updates.length > 0) {
+			const event = updates.shift();
+			if (event) yield event;
+			else await new Promise((resolve) => {
+				wake = resolve;
+			});
+		}
+		if (failure !== void 0) throw failure;
+		await prompt;
+	} finally {
+		input.abortSignal.removeEventListener("abort", onAbort);
+		if (options.disposeSessionAfterRun !== false) await session.dispose?.();
+	}
+}
+function mapAcpSessionUpdate(update, tools) {
+	if (update.sessionUpdate === "agent_message_chunk") {
+		const text = readTextContent(update.content);
+		return text === void 0 ? [] : [createAgentLoopTextDelta(text)];
+	}
+	if (update.sessionUpdate === "agent_thought_chunk") {
+		const text = readTextContent(update.content);
+		return text === void 0 ? [] : [createAgentLoopThinkingDelta(text)];
+	}
+	if (update.sessionUpdate === "tool_call") {
+		if (!update.toolCallId || !update.title) return [];
+		const name = update.name?.trim() || update.title;
+		const state = {
+			input: update.rawInput,
+			name
+		};
+		tools.set(update.toolCallId, state);
+		const start = createAgentLoopToolExecutionStart({
+			input: state.input,
+			toolCallId: update.toolCallId,
+			toolName: state.name
+		});
+		if (update.status === "completed" || update.status === "failed") {
+			tools.delete(update.toolCallId);
+			return [start, createAgentLoopToolExecutionEnd({
+				isError: update.status === "failed",
+				result: update.rawOutput,
+				toolCallId: update.toolCallId,
+				toolName: state.name
+			})];
+		}
+		return [start];
+	}
+	if (update.sessionUpdate !== "tool_call_update") return [];
+	if (!update.toolCallId) return [];
+	const prior = tools.get(update.toolCallId);
+	const state = {
+		input: update.rawInput ?? prior?.input,
+		name: update.name?.trim() || update.title?.trim() || prior?.name || update.toolCallId
+	};
+	tools.set(update.toolCallId, state);
+	if (update.status === "completed" || update.status === "failed") {
+		tools.delete(update.toolCallId);
+		return [createAgentLoopToolExecutionEnd({
+			isError: update.status === "failed",
+			result: update.rawOutput,
+			toolCallId: update.toolCallId,
+			toolName: state.name
+		})];
+	}
+	return [createAgentLoopToolExecutionUpdate({
+		input: state.input,
+		partialResult: update.rawOutput,
+		toolCallId: update.toolCallId,
+		toolName: state.name
+	})];
+}
+function readTextContent(content) {
+	if (!isRecord(content) || content.type !== "text" || typeof content.text !== "string") return void 0;
+	return content.text;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+//#endregion
+//#region src/infrastructure/acp/acp-agent-server.ts
+function createAcpAgentServer(options) {
+	const sessions = /* @__PURE__ */ new Set();
+	const active = /* @__PURE__ */ new Map();
+	return acp.agent({ name: options.agentName ?? "rivus" }).onRequest(acp.methods.agent.initialize, ({ params }) => ({
+		agentCapabilities: {},
+		agentInfo: {
+			name: options.agentName ?? "rivus",
+			version: "1"
+		},
+		protocolVersion: params.protocolVersion === acp.PROTOCOL_VERSION ? params.protocolVersion : acp.PROTOCOL_VERSION
+	})).onRequest(acp.methods.agent.session.new, () => {
+		const sessionId = randomUUID();
+		sessions.add(sessionId);
+		return { sessionId };
+	}).onRequest(acp.methods.agent.session.prompt, async ({ client, params }) => {
+		if (!sessions.has(params.sessionId)) throw new Error(`Unknown ACP session: ${params.sessionId}`);
+		if (active.has(params.sessionId)) throw new Error(`ACP session is already active: ${params.sessionId}`);
+		const controller = new AbortController();
+		active.set(params.sessionId, controller);
+		const sessionKey = `acp:${params.sessionId}`;
+		const releasePermissionBridge = options.permissionBridge?.bind(sessionKey, async (request) => {
+			const response = await client.request(acp.methods.client.session.requestPermission, {
+				options: request.options.map((option) => ({ ...option })),
+				sessionId: params.sessionId,
+				toolCall: {
+					...request.toolCall.rawInput === void 0 ? {} : { rawInput: request.toolCall.rawInput },
+					...request.toolCall.title === void 0 ? {} : { title: request.toolCall.title },
+					toolCallId: request.toolCall.toolCallId
+				}
+			});
+			return response.outcome.outcome === "selected" ? { optionId: response.outcome.optionId } : void 0;
+		});
+		try {
+			await Effect.runPromise(options.loop.run({
+				abortSignal: controller.signal,
+				runId: randomUUID(),
+				sessionKey,
+				text: readPromptText(params.prompt)
+			}).pipe(Stream.runForEach((event) => Effect.tryPromise({
+				catch: (cause) => cause,
+				try: async () => {
+					const update = mapAgentLoopEvent(event);
+					if (update) await client.notify(acp.methods.client.session.update, {
+						sessionId: params.sessionId,
+						update
+					});
+				}
+			}))));
+			return { stopReason: controller.signal.aborted ? "cancelled" : "end_turn" };
+		} finally {
+			releasePermissionBridge?.();
+			active.delete(params.sessionId);
+		}
+	}).onNotification(acp.methods.agent.session.cancel, ({ params }) => {
+		active.get(params.sessionId)?.abort();
+	});
+}
+async function serveAcpAgentOnStdio(app) {
+	const stream = acp.ndJsonStream(Writable.toWeb(process.stdout), Readable.toWeb(process.stdin));
+	await app.connect(stream).closed;
+}
+function readPromptText(prompt) {
+	const parts = prompt.flatMap((content) => content.type === "text" ? [content.text] : []);
+	if (parts.length !== prompt.length) throw new Error("Rivus ACP facade currently accepts text prompt content only");
+	return parts.join("\n");
+}
+function mapAgentLoopEvent(event) {
+	if (event.type === "assistant_text_delta") return {
+		content: {
+			text: event.delta,
+			type: "text"
+		},
+		sessionUpdate: "agent_message_chunk"
+	};
+	if (event.type === "assistant_thinking_delta") return {
+		content: {
+			text: event.delta,
+			type: "text"
+		},
+		sessionUpdate: "agent_thought_chunk"
+	};
+	if (event.type === "tool_execution_start") return {
+		name: event.toolName,
+		rawInput: event.input,
+		sessionUpdate: "tool_call",
+		status: "in_progress",
+		title: event.toolName,
+		toolCallId: event.toolCallId
+	};
+	if (event.type === "tool_execution_update") return {
+		name: event.toolName,
+		rawInput: event.input,
+		rawOutput: event.partialResult,
+		sessionUpdate: "tool_call_update",
+		status: "in_progress",
+		title: event.toolName,
+		toolCallId: event.toolCallId
+	};
+	if (event.type === "tool_execution_end") return {
+		name: event.toolName,
+		rawOutput: event.result,
+		sessionUpdate: "tool_call_update",
+		status: event.isError ? "failed" : "completed",
+		title: event.toolName,
+		toolCallId: event.toolCallId
+	};
+}
+//#endregion
+//#region src/infrastructure/acp/acp-permission-bridge.ts
+function createAcpPermissionBridge() {
+	const policies = /* @__PURE__ */ new Map();
+	return {
+		bind: (sessionKey, policy) => {
+			if (policies.has(sessionKey)) throw new Error(`ACP permission bridge is already bound: ${sessionKey}`);
+			policies.set(sessionKey, policy);
+			return () => {
+				if (policies.get(sessionKey) === policy) policies.delete(sessionKey);
+			};
+		},
+		policy: async (request, context) => policies.get(context.sessionKey)?.(request)
+	};
+}
+//#endregion
+//#region src/infrastructure/acp/acp-permission-policy.ts
+async function decideAcpPermission(request, policy) {
+	const selection = await policy?.(request);
+	if (!selection || !request.options.some((option) => option.optionId === selection.optionId)) return { outcome: "cancelled" };
+	return {
+		optionId: selection.optionId,
+		outcome: "selected"
+	};
+}
+//#endregion
+//#region src/infrastructure/acp/acp-stdio-agent-loop.ts
+function createAcpStdioAgentLoop(options) {
+	let pendingConnection;
+	let activeConnection;
+	let ownedChild;
+	const sessionKeys = /* @__PURE__ */ new Map();
+	const resolveConnection = () => {
+		if (pendingConnection) return pendingConnection;
+		let current;
+		current = openConnection(options, sessionKeys, (child) => {
+			ownedChild = child;
+		});
+		pendingConnection = current;
+		current.then((processConnection) => {
+			if (pendingConnection !== current) {
+				processConnection.connection.close();
+				terminateChild(processConnection.child, options.terminationTimeoutMs);
+				return;
+			}
+			activeConnection = processConnection;
+			processConnection.connection.closed.finally(() => {
+				if (pendingConnection !== current) return;
+				pendingConnection = void 0;
+				activeConnection = void 0;
+				if (ownedChild === processConnection.child) ownedChild = void 0;
+				sessionKeys.clear();
+				for (const session of processConnection.sessions.values()) session.dispose();
+				processConnection.sessions.clear();
+				terminateChild(processConnection.child, options.terminationTimeoutMs);
+			});
+		}, () => {
+			if (pendingConnection === current) {
+				pendingConnection = void 0;
+				activeConnection = void 0;
+				ownedChild = void 0;
+				sessionKeys.clear();
+			}
+		});
+		return current;
+	};
+	return {
+		dispose: async () => {
+			const current = pendingConnection;
+			pendingConnection = void 0;
+			const processConnection = activeConnection;
+			activeConnection = void 0;
+			if (processConnection) {
+				for (const session of processConnection.sessions.values()) session.dispose();
+				processConnection.sessions.clear();
+				processConnection.connection.close();
+			}
+			sessionKeys.clear();
+			const child = ownedChild;
+			ownedChild = void 0;
+			if (child) await terminateChild(child, options.terminationTimeoutMs);
+			await current?.catch(() => void 0);
+		},
+		loop: createAcpAgentLoop({
+			disposeSessionAfterRun: false,
+			resolveSession: async (input) => {
+				const processConnection = await resolveConnection();
+				const current = processConnection.sessions.get(input.sessionKey);
+				if (current) return current;
+				const session = new SdkAcpAgentSession(await processConnection.connection.agent.buildSession(options.workingDirectory).start(), processConnection.connection.agent);
+				sessionKeys.set(session.sessionId, input.sessionKey);
+				processConnection.sessions.set(input.sessionKey, session);
+				return session;
+			}
+		})
+	};
+}
+var SdkAcpAgentSession = class {
+	session;
+	agent;
+	constructor(session, agent) {
+		this.session = session;
+		this.agent = agent;
+	}
+	get sessionId() {
+		return this.session.sessionId;
+	}
+	cancel() {
+		return this.agent.notify(acp.methods.agent.session.cancel, { sessionId: this.session.sessionId });
+	}
+	dispose() {
+		this.session.dispose();
+	}
+	async prompt(text, onUpdate) {
+		const failure = this.session.prompt(text).then(() => new Promise(() => void 0), (error) => Promise.reject(error));
+		for (;;) {
+			const message = await Promise.race([this.session.nextUpdate(), failure]);
+			if (message.kind === "stop") return { stopReason: message.stopReason };
+			onUpdate(message.update);
+		}
+	}
+};
+async function openConnection(options, sessionKeys, onSpawn) {
+	const child = spawn(options.command, [...options.arguments ?? []], {
+		cwd: options.workingDirectory,
+		env: { ...options.environment },
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		]
+	});
+	onSpawn(child);
+	child.stderr.setEncoding("utf8");
+	if (options.onStderr) child.stderr.on("data", options.onStderr);
+	else child.stderr.resume();
+	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) };
+	});
+	const stream = acp.ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+	const connection = app.connect(stream);
+	try {
+		const initialized = await withTimeout(connection.agent.request(acp.methods.agent.initialize, {
+			clientCapabilities: {},
+			clientInfo: {
+				name: options.clientName ?? "rivus",
+				version: "1"
+			},
+			protocolVersion: acp.PROTOCOL_VERSION
+		}), 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 {
+			child,
+			connection,
+			sessions: /* @__PURE__ */ new Map()
+		};
+	} catch (error) {
+		connection.close(error);
+		await terminateChild(child, options.terminationTimeoutMs);
+		throw error;
+	}
+}
+function toPermissionRequest(request) {
+	return {
+		options: request.options,
+		sessionId: request.sessionId,
+		toolCall: {
+			...request.toolCall.rawInput === void 0 ? {} : { rawInput: request.toolCall.rawInput },
+			...request.toolCall.title == null ? {} : { title: request.toolCall.title },
+			toolCallId: request.toolCall.toolCallId
+		}
+	};
+}
+async function terminateChild(child, timeoutMs = 2e3) {
+	if (child.exitCode !== null || child.signalCode !== null) return;
+	child.kill("SIGTERM");
+	if (await waitForChildExit(child, timeoutMs)) return;
+	child.kill("SIGKILL");
+	if (!await waitForChildExit(child, timeoutMs)) throw new Error(`ACP child did not exit after SIGKILL within ${timeoutMs}ms`);
+}
+function waitForChildExit(child, timeoutMs) {
+	if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(true);
+	return new Promise((resolve) => {
+		const onExit = () => {
+			clearTimeout(timeout);
+			resolve(true);
+		};
+		const timeout = setTimeout(() => {
+			child.removeListener("exit", onExit);
+			resolve(false);
+		}, timeoutMs);
+		timeout.unref();
+		child.once("exit", onExit);
+	});
+}
+function withTimeout(promise, timeoutMs, message) {
+	return new Promise((resolve, reject) => {
+		const timeout = setTimeout(() => reject(/* @__PURE__ */ new Error(`${message} after ${timeoutMs}ms`)), timeoutMs);
+		promise.then((value) => {
+			clearTimeout(timeout);
+			resolve(value);
+		}, (error) => {
+			clearTimeout(timeout);
+			reject(error);
+		});
+	});
+}
+//#endregion
+export { createAcpAgentLoop, createAcpAgentServer, createAcpPermissionBridge, createAcpStdioAgentLoop, decideAcpPermission, serveAcpAgentOnStdio };