@alexkroman1/aai 0.9.3 → 0.10.1

package/dist/session-BkN9u0ni.js

@@ -0,0 +1,683 @@
+import { DEFAULT_INSTRUCTIONS } from "./types.js";
+import { errorDetail, errorMessage, toolError } from "./_utils.js";
+import { HOOK_TIMEOUT_MS, MAX_TOOL_RESULT_CHARS } from "./protocol.js";
+import { consoleLogger } from "./runtime.js";
+import { activeSessionsUpDown, bargeInCounter, idleTimeoutCounter, sessionCounter, toolCallCounter, toolCallDuration, toolCallErrorCounter, tracer, turnCounter, turnStepsHistogram } from "./telemetry.js";
+import { connectS2s, defaultCreateS2sWebSocket } from "./s2s.js";
+//#region _session-ctx.ts
+const DEFAULT_MAX_HISTORY = 200;
+function buildCtx(opts) {
+	const { id, agentConfig, hookInvoker, log } = opts;
+	const maxHistory = opts.maxHistory ?? DEFAULT_MAX_HISTORY;
+	/** Track in-flight hook promises so they can be awaited during shutdown. */
+	const pendingHooks = /* @__PURE__ */ new Set();
+	const ctx = {
+		...opts,
+		s2s: null,
+		pendingTools: [],
+		toolCallCount: 0,
+		turnPromise: null,
+		conversationMessages: [],
+		maxHistory,
+		currentReplyId: null,
+		filterChain: Promise.resolve(),
+		resolveTurnConfig() {
+			if (!hookInvoker) return Promise.resolve(null);
+			return hookInvoker.resolveTurnConfig(id, HOOK_TIMEOUT_MS);
+		},
+		consumeToolCallStep(turnConfig, _name, replyId) {
+			if (replyId === null || replyId !== ctx.currentReplyId) return toolError("Reply was interrupted. Discarding stale tool call.");
+			const maxSteps = turnConfig?.maxSteps ?? agentConfig.maxSteps;
+			ctx.toolCallCount++;
+			if (maxSteps !== void 0 && ctx.toolCallCount > maxSteps) {
+				log.info("maxSteps exceeded, refusing tool call", {
+					toolCallCount: ctx.toolCallCount,
+					maxSteps
+				});
+				return toolError("Maximum tool steps reached. Please respond to the user now.");
+			}
+			return null;
+		},
+		fireHook(name, fn) {
+			if (!hookInvoker) return;
+			const notifyOnError = (err) => {
+				log.warn(`${name} hook failed`, { err: errorMessage(err) });
+				if (name !== "onError") try {
+					const r = hookInvoker.onError(id, { message: errorMessage(err) });
+					if (r && typeof r.catch === "function") r.catch((e) => {
+						log.warn("onError hook failed", { err: errorMessage(e) });
+					});
+				} catch (e) {
+					log.warn("onError hook failed", { err: errorMessage(e) });
+				}
+			};
+			try {
+				const p = fn(hookInvoker).catch(notifyOnError).finally(() => pendingHooks.delete(p));
+				pendingHooks.add(p);
+			} catch (err) {
+				notifyOnError(err);
+			}
+		},
+		async drainHooks() {
+			if (pendingHooks.size > 0) await Promise.all([...pendingHooks]);
+		},
+		pushMessages(...msgs) {
+			ctx.conversationMessages.push(...msgs);
+			if (maxHistory > 0 && ctx.conversationMessages.length > maxHistory) ctx.conversationMessages = ctx.conversationMessages.slice(-maxHistory);
+		}
+	};
+	return ctx;
+}
+//#endregion
+//#region _session-otel.ts
+/**
+* Complete a tool call by truncating the result, emitting a `tool_call_done` event,
+* and accumulating the result in `ctx.pendingTools` — but only if the reply that
+* initiated this call is still active.
+*/
+function finishToolCall(ctx, callId, result, replyId) {
+	const truncatedResult = result.length > 4e3 ? result.slice(0, MAX_TOOL_RESULT_CHARS) : result;
+	ctx.client.event({
+		type: "tool_call_done",
+		toolCallId: callId,
+		result: truncatedResult
+	});
+	if (replyId !== null && replyId === ctx.currentReplyId) {
+		ctx.pendingTools.push({
+			callId,
+			result
+		});
+		if (ctx.maxHistory > 0 && ctx.pendingTools.length > ctx.maxHistory) ctx.pendingTools.shift();
+	}
+}
+/**
+* Orchestrate the full tool call pipeline for a single S2S tool invocation.
+*
+* Steps: resolve per-turn config → check step/tool limits → run middleware
+* `interceptToolCall` (which may block, return a cached result, or modify args)
+* → execute the tool → run `afterToolCall` middleware → record metrics and
+* finish via {@link finishToolCall}. Each step is wrapped in an OpenTelemetry
+* span (`tool.call`) with agent/session/tool attributes.
+*
+* @param ctx - The shared mutable session context (see {@link S2sSessionCtx}).
+* @param detail - The tool call details from the S2S API (call ID, name, parsed args).
+*/
+async function handleToolCall(ctx, detail) {
+	const { callId, name, args: parsedArgs } = detail;
+	const replyId = ctx.currentReplyId;
+	const span = tracer.startSpan("tool.call", { attributes: {
+		"aai.tool.name": name,
+		"aai.tool.call_id": callId,
+		"aai.agent": ctx.agent,
+		"aai.session.id": ctx.id
+	} });
+	const startTime = performance.now();
+	ctx.client.event({
+		type: "tool_call_start",
+		toolCallId: callId,
+		toolName: name,
+		args: parsedArgs
+	});
+	let turnConfig;
+	try {
+		turnConfig = await ctx.resolveTurnConfig();
+	} catch (err) {
+		const msg = `resolveTurnConfig hook error: ${errorMessage(err)}`;
+		ctx.log.error(msg);
+		span.setStatus({
+			code: 2,
+			message: msg
+		});
+		span.end();
+		finishToolCall(ctx, callId, toolError(msg), replyId);
+		return;
+	}
+	const refused = ctx.consumeToolCallStep(turnConfig, name, replyId);
+	if (refused !== null) {
+		span.setAttribute("aai.tool.refused", true);
+		span.end();
+		finishToolCall(ctx, callId, refused, replyId);
+		return;
+	}
+	ctx.fireHook("onStep", (h) => h.onStep(ctx.id, {
+		stepNumber: ctx.toolCallCount - 1,
+		toolCalls: [{
+			toolName: name,
+			args: parsedArgs
+		}],
+		text: ""
+	}, HOOK_TIMEOUT_MS));
+	ctx.log.info("S2S tool call", {
+		tool: name,
+		callId,
+		args: parsedArgs,
+		agent: ctx.agent
+	});
+	toolCallCounter.add(1, {
+		agent: ctx.agent,
+		tool: name
+	});
+	let effectiveArgs = parsedArgs;
+	if (ctx.hookInvoker?.interceptToolCall) try {
+		const ic = await ctx.hookInvoker.interceptToolCall(ctx.id, name, parsedArgs, HOOK_TIMEOUT_MS);
+		if (ic?.type === "block") {
+			span.setAttribute("aai.tool.blocked", true);
+			span.end();
+			finishToolCall(ctx, callId, toolError(ic.reason), replyId);
+			return;
+		}
+		if (ic?.type === "result") {
+			span.setAttribute("aai.tool.cached", true);
+			span.end();
+			finishToolCall(ctx, callId, ic.result, replyId);
+			ctx.fireHook("afterToolCall", (h) => h.afterToolCall?.(ctx.id, name, parsedArgs, ic.result, 5e3) ?? Promise.resolve());
+			return;
+		}
+		if (ic?.type === "args") effectiveArgs = ic.args;
+	} catch (err) {
+		ctx.log.warn("interceptToolCall middleware failed (fail-open, tool call proceeds)", {
+			err: errorMessage(err),
+			tool: name
+		});
+	}
+	const onUpdate = (data) => {
+		const serialized = typeof data === "string" ? data : JSON.stringify(data);
+		const truncated = serialized.length > 4e3 ? serialized.slice(0, MAX_TOOL_RESULT_CHARS) : serialized;
+		ctx.client.event({
+			type: "tool_call_update",
+			toolCallId: callId,
+			data: truncated
+		});
+	};
+	let result;
+	try {
+		result = await ctx.executeTool(name, effectiveArgs, ctx.id, ctx.conversationMessages, onUpdate);
+	} catch (err) {
+		const msg = errorMessage(err);
+		ctx.log.error("Tool execution failed", {
+			tool: name,
+			error: errorDetail(err)
+		});
+		toolCallErrorCounter.add(1, {
+			agent: ctx.agent,
+			tool: name
+		});
+		span.setStatus({
+			code: 2,
+			message: msg
+		});
+		span.recordException(err instanceof Error ? err : new Error(msg));
+		result = toolError(msg);
+	}
+	if (ctx.hookInvoker?.afterToolCall) ctx.fireHook("afterToolCall", (h) => h.afterToolCall?.(ctx.id, name, effectiveArgs, result, 5e3) ?? Promise.resolve());
+	toolCallDuration.record((performance.now() - startTime) / 1e3, {
+		agent: ctx.agent,
+		tool: name
+	});
+	ctx.log.info("S2S tool result", {
+		tool: name,
+		callId,
+		resultLength: result.length
+	});
+	finishToolCall(ctx, callId, result, replyId);
+	span.end();
+}
+function handleUserTranscript(ctx, text) {
+	ctx.log.info("S2S user transcript", { text });
+	turnCounter.add(1, { agent: ctx.agent });
+	ctx.client.event({
+		type: "transcript",
+		text,
+		isFinal: true
+	});
+	ctx.client.event({
+		type: "turn",
+		text
+	});
+	const processFiltered = (filtered) => {
+		ctx.pushMessages({
+			role: "user",
+			content: filtered
+		});
+		const fireTurn = () => ctx.fireHook("onTurn", (h) => h.onTurn(ctx.id, filtered, HOOK_TIMEOUT_MS));
+		if (!ctx.hookInvoker?.beforeTurn) {
+			fireTurn();
+			return;
+		}
+		ctx.hookInvoker.beforeTurn(ctx.id, filtered, HOOK_TIMEOUT_MS).then((reason) => {
+			if (reason) {
+				ctx.log.info("Turn blocked by middleware", { reason });
+				ctx.client.event({
+					type: "chat",
+					text: reason
+				});
+				ctx.client.event({ type: "tts_done" });
+			} else fireTurn();
+		}).catch((err) => {
+			ctx.log.warn("beforeTurn hook failed", { error: errorMessage(err) });
+			fireTurn();
+		});
+	};
+	if (!ctx.hookInvoker?.filterInput) {
+		processFiltered(text);
+		return;
+	}
+	ctx.hookInvoker.filterInput(ctx.id, text, HOOK_TIMEOUT_MS).then((filtered) => processFiltered(filtered)).catch((err) => {
+		ctx.log.warn("filterInput hook failed", { error: errorMessage(err) });
+		processFiltered(text);
+	});
+}
+function handleAgentTranscriptDelta(ctx, text) {
+	const filterOutput = ctx.hookInvoker?.filterOutput;
+	if (!filterOutput) {
+		ctx.client.event({
+			type: "chat_delta",
+			text
+		});
+		return;
+	}
+	ctx.filterChain = ctx.filterChain.then(async () => {
+		try {
+			const f = await filterOutput.call(ctx.hookInvoker, ctx.id, text, HOOK_TIMEOUT_MS);
+			ctx.client.event({
+				type: "chat_delta",
+				text: f
+			});
+		} catch (err) {
+			ctx.log.warn("filterOutput hook failed", { error: errorMessage(err) });
+			ctx.client.event({
+				type: "chat_delta",
+				text
+			});
+		}
+	});
+}
+function handleAgentTranscript(ctx, text, interrupted) {
+	const emit = (t) => {
+		ctx.client.event({
+			type: "chat",
+			text: t
+		});
+		if (!interrupted) ctx.pushMessages({
+			role: "assistant",
+			content: t
+		});
+	};
+	const filterOutput = ctx.hookInvoker?.filterOutput;
+	if (!filterOutput) {
+		emit(text);
+		return;
+	}
+	ctx.filterChain = ctx.filterChain.then(async () => {
+		try {
+			emit(await filterOutput.call(ctx.hookInvoker, ctx.id, text, HOOK_TIMEOUT_MS));
+		} catch (err) {
+			ctx.log.warn("filterOutput hook failed", { error: errorMessage(err) });
+			emit(text);
+		}
+	});
+}
+function handleReplyDone(ctx, status) {
+	if (status === "interrupted") {
+		ctx.log.info("S2S reply interrupted (barge-in)");
+		bargeInCounter.add(1, { agent: ctx.agent });
+		ctx.currentReplyId = null;
+		ctx.pendingTools = [];
+		ctx.filterChain = Promise.resolve();
+		ctx.client.event({ type: "cancelled" });
+		return;
+	}
+	const doneReplyId = ctx.currentReplyId;
+	const sendPending = () => {
+		if (ctx.currentReplyId !== doneReplyId) {
+			ctx.pendingTools = [];
+			return;
+		}
+		if (ctx.pendingTools.length > 0) {
+			for (const tool of ctx.pendingTools) ctx.s2s?.sendToolResult(tool.callId, tool.result);
+			ctx.pendingTools = [];
+		} else {
+			const stepsUsed = ctx.toolCallCount;
+			if (stepsUsed > 0) {
+				ctx.log.info("Turn complete", {
+					steps: stepsUsed,
+					agent: ctx.agent
+				});
+				turnStepsHistogram.record(stepsUsed, { agent: ctx.agent });
+			}
+			if (ctx.hookInvoker?.afterTurn) {
+				const last = ctx.conversationMessages.at(-1);
+				ctx.fireHook("afterTurn", (h) => h.afterTurn?.(ctx.id, last?.content ?? "", 5e3) ?? Promise.resolve());
+			}
+			ctx.client.playAudioDone();
+			ctx.client.event({ type: "tts_done" });
+		}
+	};
+	if (ctx.turnPromise !== null) ctx.turnPromise.then(sendPending);
+	else sendPending();
+}
+/**
+* Wire all S2S events to the client sink, hooks, and session state.
+*
+* Registers listeners on the S2S handle for: ready, session expiry, speech
+* start/stop, user/agent transcripts, reply lifecycle, tool calls, audio
+* chunks, errors, and close. Each listener delegates to a focused handler
+* function that updates `ctx` and emits client events.
+*
+* @param ctx - The shared mutable session context.
+* @param handle - The S2S WebSocket handle to listen on.
+* @param opts - Optional overrides for listener behavior.
+*/
+function setupListeners(ctx, handle, opts) {
+	handle.on("ready", ({ sessionId }) => ctx.log.info("S2S session ready", { sessionId }));
+	handle.on("sessionExpired", () => {
+		if (opts?.onSessionExpired) opts.onSessionExpired();
+		else {
+			ctx.log.info("S2S session expired");
+			handle.close();
+		}
+	});
+	handle.on("speechStarted", () => ctx.client.event({ type: "speech_started" }));
+	handle.on("speechStopped", () => ctx.client.event({ type: "speech_stopped" }));
+	handle.on("userTranscriptDelta", ({ text }) => ctx.client.event({
+		type: "transcript",
+		text,
+		isFinal: false
+	}));
+	handle.on("userTranscript", ({ text }) => handleUserTranscript(ctx, text));
+	handle.on("replyStarted", ({ replyId }) => {
+		ctx.toolCallCount = 0;
+		ctx.currentReplyId = replyId;
+		ctx.pendingTools = [];
+		ctx.turnPromise = null;
+		ctx.filterChain = Promise.resolve();
+	});
+	handle.on("audio", ({ audio }) => ctx.client.playAudioChunk(audio));
+	handle.on("agentTranscriptDelta", ({ text }) => handleAgentTranscriptDelta(ctx, text));
+	handle.on("agentTranscript", ({ text, interrupted }) => handleAgentTranscript(ctx, text, interrupted));
+	handle.on("toolCall", (detail) => {
+		const p = handleToolCall(ctx, detail).catch((err) => {
+			ctx.log.error("Tool call handler failed", { err: errorMessage(err) });
+		});
+		ctx.turnPromise = (ctx.turnPromise ?? Promise.resolve()).then(() => p);
+	});
+	handle.on("replyDone", ({ status }) => handleReplyDone(ctx, status));
+	handle.on("error", ({ code, message }) => {
+		ctx.log.error("S2S error", {
+			code,
+			message
+		});
+		ctx.client.event({
+			type: "error",
+			code: "internal",
+			message
+		});
+		handle.close();
+	});
+	handle.on("close", () => {
+		ctx.log.info("S2S closed");
+		ctx.s2s = null;
+		ctx.currentReplyId = null;
+		ctx.pendingTools = [];
+	});
+}
+//#endregion
+//#region _session-persist.ts
+const PERSIST_PREFIX = "__persist:";
+function persistKey(sessionId) {
+	return `${PERSIST_PREFIX}${sessionId}`;
+}
+async function restorePersistedSession(persistence, resumeFrom, ctx, log) {
+	const persisted = await persistence.kv.get(persistKey(resumeFrom));
+	if (!persisted) return null;
+	log.info("Restoring persisted session", { resumeFrom });
+	persistence.setState(persisted.state);
+	if (persisted.messages.length > 0) ctx.pushMessages(...persisted.messages);
+	return persisted.s2sSessionId;
+}
+async function saveSessionData(persistence, sessionId, ctx, s2sSessionId, log, cleanupKey) {
+	const data = {
+		s2sSessionId,
+		messages: ctx.conversationMessages,
+		state: persistence.getState()
+	};
+	const key = persistKey(sessionId);
+	const ops = [persistence.kv.set(key, data, { expireIn: persistence.ttl })];
+	if (cleanupKey && cleanupKey !== sessionId) ops.push(persistence.kv.delete(persistKey(cleanupKey)));
+	await Promise.all(ops);
+	log.info("Session persisted", { sessionId });
+}
+//#endregion
+//#region system-prompt.ts
+function getFormattedDate() {
+	return (/* @__PURE__ */ new Date()).toLocaleDateString("en-US", {
+		weekday: "long",
+		year: "numeric",
+		month: "long",
+		day: "numeric"
+	});
+}
+const VOICE_RULES = "\n\nCRITICAL OUTPUT RULES — you MUST follow these for EVERY response:\nYour response will be spoken aloud by a TTS system and displayed as plain text.\n- NEVER use markdown: no **, no *, no _, no #, no `, no [](), no ---\n- NEVER use bullet points (-, *, •) or numbered lists (1., 2.)\n- NEVER use code blocks or inline code\n- NEVER mention tools, search, APIs, or technical failures to the user. If a tool returns no results, just answer naturally without explaining why.\n- Write exactly as you would say it out loud to a friend\n- Use short conversational sentences. To list things, say \"First,\" \"Next,\" \"Finally,\"\n- Keep responses concise — 1 to 3 sentences max";
+/**
+* Build the system prompt sent to the LLM from the agent configuration.
+*
+* Assembles the default instructions, today's date, agent-specific instructions,
+* and optional sections for tool usage preamble and voice output rules.
+*
+* @param config - The serializable agent configuration (name, instructions, etc.).
+* @param opts.hasTools - When `true`, appends a preamble instructing the LLM to
+*   speak a brief phrase before each tool call to fill silence.
+* @param opts.voice - When `true`, appends strict voice-specific output rules
+*   (no markdown, no bullet points, conversational tone, concise responses).
+* @returns The assembled system prompt string.
+*/
+function buildSystemPrompt(config, opts) {
+	const { hasTools } = opts;
+	const agentInstructions = config.instructions && config.instructions !== DEFAULT_INSTRUCTIONS ? `\n\nAgent-Specific Instructions:\n${config.instructions}` : "";
+	const toolPreamble = hasTools ? "\n\nWhen you decide to use a tool, ALWAYS say a brief natural phrase BEFORE the tool call (e.g. \"Let me look that up\" or \"One moment while I check\"). This fills silence while the tool executes. Keep preambles to one short sentence." : "";
+	return DEFAULT_INSTRUCTIONS + `\n\nToday's date is ${getFormattedDate()}.` + agentInstructions + toolPreamble + (opts.voice ? VOICE_RULES : "");
+}
+//#endregion
+//#region session.ts
+/** @internal Not part of the public API. Exposed for testing only. */
+const _internals = { connectS2s };
+const DEFAULT_IDLE_TIMEOUT_MS = 3e5;
+function createIdleTimer(opts) {
+	if (opts.timeoutMs <= 0) return {
+		reset() {},
+		clear() {}
+	};
+	let timer = null;
+	return {
+		reset() {
+			if (timer !== null) clearTimeout(timer);
+			timer = setTimeout(() => {
+				opts.log.info("S2S idle timeout", {
+					timeoutMs: opts.timeoutMs,
+					agent: opts.agent
+				});
+				idleTimeoutCounter.add(1, { agent: opts.agent });
+				opts.client.event({ type: "idle_timeout" });
+				opts.ctx.s2s?.close();
+			}, opts.timeoutMs);
+		},
+		clear() {
+			if (timer !== null) {
+				clearTimeout(timer);
+				timer = null;
+			}
+		}
+	};
+}
+/**
+* Create a Speech-to-Speech backed session implementing the {@link Session} interface.
+*
+* Connects to AssemblyAI's S2S WebSocket, configures the system prompt and tools,
+* and wires up event listeners for user transcripts, agent replies, tool calls,
+* barge-ins, and session lifecycle. Manages reconnection on `onReset` via a
+* `connectGeneration` guard that prevents stale connection attempts from overwriting
+* newer ones during rapid resets. A `sessionAbort` AbortController is used to
+* coordinate cleanup on `stop()`.
+*
+* @param opts - Session configuration. See {@link S2sSessionOptions} for all fields
+*   including the agent config, tool schemas, API key, and optional hooks.
+* @returns A {@link Session} with `start`, `stop`, `onAudio`, `onReset`, and other
+*   lifecycle methods.
+*/
+function createS2sSession(opts) {
+	const { id, agent, client, toolSchemas, apiKey, s2sConfig, executeTool, createWebSocket = defaultCreateS2sWebSocket, hookInvoker, logger: log = consoleLogger, persistence, resumeFrom } = opts;
+	const agentConfig = opts.skipGreeting ? {
+		...opts.agentConfig,
+		greeting: ""
+	} : opts.agentConfig;
+	const systemPrompt = buildSystemPrompt(agentConfig, {
+		hasTools: toolSchemas.length > 0 || (agentConfig.builtinTools?.length ?? 0) > 0,
+		voice: true
+	});
+	const s2sTools = toolSchemas.map((ts) => ({
+		type: "function",
+		name: ts.name,
+		description: ts.description,
+		parameters: ts.parameters
+	}));
+	const sessionAbort = new AbortController();
+	const ctx = buildCtx({
+		id,
+		agent,
+		client,
+		agentConfig,
+		executeTool,
+		hookInvoker,
+		log,
+		maxHistory: opts.maxHistory
+	});
+	const rawTimeout = agentConfig.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+	const idle = createIdleTimer({
+		timeoutMs: rawTimeout === 0 || !Number.isFinite(rawTimeout) ? 0 : rawTimeout,
+		agent,
+		log,
+		client,
+		ctx
+	});
+	let currentS2sSessionId = null;
+	let resumeS2sId = null;
+	const pendingCleanupKey = resumeFrom;
+	/** Monotonically increasing counter bumped on each connectAndSetup call.
+	*  Only the most recent invocation is allowed to set ctx.s2s, preventing
+	*  earlier completions from overwriting a newer connection during rapid resets. */
+	let connectGeneration = 0;
+	/** The session.update payload shared by fresh and fallback paths. */
+	const sessionUpdatePayload = {
+		systemPrompt,
+		tools: s2sTools,
+		...agentConfig.greeting ? { greeting: agentConfig.greeting } : {}
+	};
+	async function connectAndSetup() {
+		const generation = ++connectGeneration;
+		try {
+			const handle = await _internals.connectS2s({
+				apiKey,
+				config: s2sConfig,
+				createWebSocket,
+				logger: log
+			});
+			if (sessionAbort.signal.aborted || generation !== connectGeneration) {
+				handle.close();
+				return;
+			}
+			handle.on("ready", ({ sessionId: s2sId }) => {
+				currentS2sSessionId = s2sId;
+			});
+			if (resumeS2sId) {
+				const s2sId = resumeS2sId;
+				resumeS2sId = null;
+				let resumeFallbackUsed = false;
+				setupListeners(ctx, handle, { onSessionExpired: () => {
+					if (!resumeFallbackUsed) {
+						resumeFallbackUsed = true;
+						log.info("S2S session resume failed, falling back to new session");
+						handle.updateSession(sessionUpdatePayload);
+					} else {
+						ctx.log.info("S2S session expired");
+						handle.close();
+					}
+				} });
+				handle.resumeSession(s2sId);
+			} else {
+				setupListeners(ctx, handle);
+				handle.updateSession(sessionUpdatePayload);
+			}
+			ctx.s2s = handle;
+			idle.reset();
+		} catch (err) {
+			const msg = errorMessage(err);
+			log.error("S2S connect failed", { error: errorDetail(err) });
+			client.event({
+				type: "error",
+				code: "internal",
+				message: msg
+			});
+		}
+	}
+	return {
+		async start() {
+			if (persistence && resumeFrom) try {
+				const s2sId = await restorePersistedSession(persistence, resumeFrom, ctx, log);
+				if (s2sId) resumeS2sId = s2sId;
+			} catch (err) {
+				log.warn("Failed to restore persisted session", { error: errorMessage(err) });
+			}
+			sessionCounter.add(1, { agent });
+			activeSessionsUpDown.add(1, { agent });
+			ctx.fireHook("onConnect", (h) => h.onConnect(id, HOOK_TIMEOUT_MS));
+			await connectAndSetup();
+		},
+		async stop() {
+			if (sessionAbort.signal.aborted) return;
+			sessionAbort.abort();
+			idle.clear();
+			activeSessionsUpDown.add(-1, { agent });
+			if (ctx.turnPromise !== null) await ctx.turnPromise;
+			await ctx.drainHooks();
+			if (persistence) try {
+				await saveSessionData(persistence, id, ctx, currentS2sSessionId, log, pendingCleanupKey);
+			} catch (err) {
+				log.warn("Failed to persist session", { error: errorMessage(err) });
+			}
+			ctx.s2s?.close();
+			ctx.fireHook("onDisconnect", (h) => h.onDisconnect(id, HOOK_TIMEOUT_MS));
+			await ctx.drainHooks();
+		},
+		onAudio(data) {
+			idle.reset();
+			ctx.s2s?.sendAudio(data);
+		},
+		onAudioReady() {},
+		onCancel() {
+			client.event({ type: "cancelled" });
+		},
+		onReset() {
+			ctx.conversationMessages = [];
+			ctx.toolCallCount = 0;
+			ctx.turnPromise = null;
+			ctx.pendingTools = [];
+			ctx.currentReplyId = null;
+			currentS2sSessionId = null;
+			idle.clear();
+			ctx.s2s?.close();
+			client.event({ type: "reset" });
+			connectAndSetup().catch((err) => log.error("S2S reset reconnect failed", { error: errorMessage(err) }));
+		},
+		onHistory(incoming) {
+			ctx.pushMessages(...incoming.map((m) => ({
+				role: m.role,
+				content: m.content
+			})));
+		},
+		waitForTurn() {
+			return ctx.turnPromise ?? Promise.resolve();
+		}
+	};
+}
+//#endregion
+export { persistKey as i, createS2sSession as n, buildSystemPrompt as r, _internals as t };