@gajae-code/coding-agent 0.11.6 → 0.11.7

package/src/sdk/transport/socket.ts

@@ -0,0 +1,197 @@
+import * as fsSync from "node:fs";
+import * as fs from "node:fs/promises";
+import * as net from "node:net";
+import * as path from "node:path";
+import { MAX_UNIX_SOCKET_PATH_BYTES } from "../../harness-control-plane/storage";
+import { authenticatePreface } from "./auth-preface";
+import type { ServeHandle, ServeOptions } from "./index";
+import type { RelayOptions, RelayPair, TransportError } from "./relay";
+import { startRelayPair } from "./relay";
+
+function socketFailure(code: string): Error {
+	return new Error(code);
+}
+
+async function validateSocketPath(socketPath: string): Promise<void> {
+	if (process.platform === "win32") throw socketFailure("unsupported_platform");
+	if (Buffer.byteLength(socketPath) > MAX_UNIX_SOCKET_PATH_BYTES) throw socketFailure("socket_path_too_long");
+	try {
+		await fs.lstat(socketPath);
+		throw socketFailure("socket_path_in_use");
+	} catch (error) {
+		if (error instanceof Error && error.message === "socket_path_in_use") throw error;
+		const code = error as NodeJS.ErrnoException;
+		if (code.code !== "ENOENT") throw error;
+	}
+	let parent: Awaited<ReturnType<typeof fs.stat>>;
+	try {
+		parent = await fs.stat(path.dirname(socketPath));
+	} catch {
+		throw socketFailure("socket_dir_insecure");
+	}
+	if (!parent.isDirectory() || parent.uid !== process.getuid?.() || (parent.mode & 0o022) !== 0)
+		throw socketFailure("socket_dir_insecure");
+}
+
+function sendTransportError(socket: net.Socket, error: TransportError): void {
+	socket.write(`${JSON.stringify(error)}\n`);
+}
+
+/** Serves authenticated SDK JSONL clients over a private Unix-domain socket. */
+export async function startSocketServe(
+	options: ServeOptions & { socketPath: string; webSocketFactory?: RelayOptions["webSocketFactory"] },
+): Promise<ServeHandle> {
+	await validateSocketPath(options.socketPath);
+	const pairs = new Set<RelayPair>();
+	const sockets = new Set<net.Socket>();
+	const connectionTasks = new Set<Promise<void>>();
+	const dialControllers = new Set<AbortController>();
+	let server: net.Server | undefined;
+	let ownedIdentity: { dev: number; ino: number } | undefined;
+	let closing: Promise<void> | undefined;
+	const done = Promise.withResolvers<void>();
+	void done.promise.catch(() => undefined);
+
+	const removeOwnedSocket = async (): Promise<void> => {
+		if (!ownedIdentity) return;
+		try {
+			const current = await fs.lstat(options.socketPath);
+			if (current.isSocket() && current.dev === ownedIdentity.dev && current.ino === ownedIdentity.ino)
+				await fs.unlink(options.socketPath);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+	};
+
+	const removeOwnedSocketSync = (): void => {
+		if (!ownedIdentity) return;
+		try {
+			const current = fsSync.lstatSync(options.socketPath);
+			if (current.isSocket() && current.dev === ownedIdentity.dev && current.ino === ownedIdentity.ino)
+				fsSync.unlinkSync(options.socketPath);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+	};
+	const cleanupOnExit = (): void => removeOwnedSocketSync();
+	process.once("exit", cleanupOnExit);
+	const close = async (fatalError?: Error): Promise<void> => {
+		if (closing) return await closing;
+		closing = (async () => {
+			const errors: Error[] = fatalError ? [fatalError] : [];
+			for (const controller of dialControllers) controller.abort();
+			for (const socket of sockets) socket.destroy();
+			const pairResults = await Promise.allSettled([...pairs].map(pair => pair.close()));
+			for (const result of pairResults) {
+				if (result.status === "rejected")
+					errors.push(result.reason instanceof Error ? result.reason : new Error(String(result.reason)));
+			}
+			const connectionResults = await Promise.allSettled([...connectionTasks]);
+			for (const result of connectionResults) {
+				if (result.status === "rejected")
+					errors.push(result.reason instanceof Error ? result.reason : new Error(String(result.reason)));
+			}
+			let displacedPath: string | undefined;
+			if (server?.listening && ownedIdentity) {
+				try {
+					const current = await fs.lstat(options.socketPath).catch(() => undefined);
+					if (current && (current.dev !== ownedIdentity.dev || current.ino !== ownedIdentity.ino)) {
+						displacedPath = `${options.socketPath}.${process.pid}.closing`;
+						await fs.rename(options.socketPath, displacedPath);
+					}
+				} catch (error) {
+					errors.push(error instanceof Error ? error : new Error(String(error)));
+				}
+			}
+			if (server?.listening) {
+				try {
+					await new Promise<void>((resolve, reject) =>
+						server?.close(error => (error ? reject(error) : resolve())),
+					);
+				} catch (error) {
+					errors.push(error instanceof Error ? error : new Error(String(error)));
+				}
+			}
+			if (displacedPath) {
+				try {
+					await fs.rename(displacedPath, options.socketPath);
+				} catch (error) {
+					errors.push(error instanceof Error ? error : new Error(String(error)));
+				}
+			}
+			try {
+				await removeOwnedSocket();
+			} catch (error) {
+				errors.push(error instanceof Error ? error : new Error(String(error)));
+			}
+			process.removeListener("exit", cleanupOnExit);
+			if (errors.length > 0) {
+				const error = new AggregateError(errors, "socket_serve_close_failed");
+				done.reject(error);
+				throw error;
+			}
+			done.resolve();
+		})();
+		return await closing;
+	};
+	const handleConnection = async (socket: net.Socket, signal: AbortSignal): Promise<void> => {
+		sockets.add(socket);
+		socket.once("close", () => sockets.delete(socket));
+		try {
+			const initialDownstreamBytes = await authenticatePreface(socket, options.token);
+			if (closing) {
+				socket.destroy();
+				return;
+			}
+			const pair = await startRelayPair({
+				...options,
+				signal,
+				downstream: socket,
+				downstreamSink: socket,
+				initialDownstreamBytes,
+				onTransportError: error => sendTransportError(socket, error),
+			});
+			pairs.add(pair);
+			try {
+				await pair.done.catch(() => undefined);
+			} finally {
+				pairs.delete(pair);
+				socket.end();
+			}
+		} catch {
+			socket.destroy();
+		}
+	};
+	server = net.createServer(socket => {
+		if (closing) {
+			socket.destroy();
+			return;
+		}
+		const controller = new AbortController();
+		dialControllers.add(controller);
+		const task = handleConnection(socket, controller.signal).finally(() => {
+			dialControllers.delete(controller);
+			connectionTasks.delete(task);
+		});
+		connectionTasks.add(task);
+		void task;
+	});
+	server.on("error", error => void close(error).catch(() => undefined));
+	await new Promise<void>((resolve, reject) => {
+		server?.once("error", reject);
+		server?.listen(options.socketPath, () => resolve());
+	});
+	const bound = await fs.lstat(options.socketPath);
+	if (!bound.isSocket()) {
+		await close();
+		throw socketFailure("socket_bind_failed");
+	}
+	ownedIdentity = { dev: bound.dev, ino: bound.ino };
+	try {
+		await fs.chmod(options.socketPath, 0o600);
+	} catch (error) {
+		await close();
+		throw error;
+	}
+	return { close, done: done.promise };
+}

package/src/sdk/transport/stdio.ts

@@ -0,0 +1,17 @@
+import type { ServeHandle, ServeOptions } from "./index";
+import { startRelayPair } from "./relay";
+
+function writeDiagnostic(value: unknown): void {
+	process.stderr.write(`${JSON.stringify(value)}\n`);
+}
+
+/** Serves one parent-owned JSONL connection over the process standard streams. */
+export async function startStdioServe(options: ServeOptions): Promise<ServeHandle> {
+	const pair = await startRelayPair({
+		...options,
+		downstream: process.stdin,
+		downstreamSink: process.stdout,
+		onTransportError: writeDiagnostic,
+	});
+	return { close: pair.close, done: pair.done };
+}

package/src/session/agent-session.ts

@@ -105,6 +105,16 @@ import {
 	type FallbackAttemptToken,
 	type FallbackTriggerClass,
 } from "@gajae-code/ai/utils/fallback-transport";
+import {
+	BTW_MAX_ANSWER_UTF8_BYTES,
+	BTW_MAX_QUESTION_UTF8_BYTES,
+	BTW_STREAM_IDLE_TIMEOUT_MS,
+	BTW_STREAM_TOTAL_TIMEOUT_MS,
+	type BtwTextExchange,
+	boundBtwExchanges,
+	truncateUtf8,
+	utf8ByteLength,
+} from "./btw-contract";
 
 export interface ForkContextSeedMetadata {
 	sourceSessionId: string;
@@ -827,7 +837,6 @@ function isLocalModelEndpoint(model: Model | undefined): boolean {
 }
 
 const IRC_REPLY_MAX_BYTES = 4096;
-const BTW_ESTABLISHMENT_TIMEOUT_MS = 15_000;
 
 export type EphemeralTurnPurpose = "btw" | "background";
 
@@ -837,8 +846,34 @@ interface EphemeralTurnBaseArgs {
 	signal?: AbortSignal;
 }
 
+export interface BtwRoleTextMessage {
+	role: "user" | "assistant";
+	text: string;
+}
+
+export interface BtwConversationScope {
+	model: Model;
+	systemPrompt: string[];
+	messages: BtwRoleTextMessage[];
+	thinkingLevel: ThinkingLevel;
+	hideThinkingSummary: boolean;
+	serviceTier: ServiceTier | undefined;
+	credentialSessionId: string;
+	providerAffinitySessionId: string;
+	sideSessionId: string;
+}
+
+export interface BtwTurnCapture {
+	question: string;
+	scope: BtwConversationScope | undefined;
+}
+
 export type EphemeralTurnArgs =
-	| (EphemeralTurnBaseArgs & { purpose: "btw" })
+	| (Omit<EphemeralTurnBaseArgs, "promptText"> & {
+			purpose: "btw";
+			turn: BtwTurnCapture;
+			contextExchanges?: readonly BtwTextExchange[];
+	  })
 	| (EphemeralTurnBaseArgs & {
 			purpose?: "background";
 			/** Internal caller-supplied, non-persistent context such as the IRC roster. */
@@ -13993,167 +14028,127 @@ export class AgentSession {
 		this.#ircRosterClaim = null;
 	}
 
+	createBtwConversationScope(instruction: string): BtwConversationScope {
+		const model = this.model;
+		if (!model) throw new Error("No active model on session");
+		const providerAffinitySessionId = this.agent.providerSessionId ?? this.agent.sessionId ?? this.sessionId;
+		return {
+			model,
+			systemPrompt: [...this.systemPrompt, instruction],
+			messages: this.#projectBtwVisibleText(this.buildDisplaySessionContext().messages),
+			thinkingLevel: this.thinkingLevel ?? ThinkingLevel.Off,
+			hideThinkingSummary: this.agent.hideThinkingSummary ?? false,
+			serviceTier: this.serviceTier,
+			credentialSessionId: providerAffinitySessionId,
+			providerAffinitySessionId,
+			sideSessionId: `${providerAffinitySessionId}:btw:${crypto.randomUUID()}`,
+		};
+	}
+
+	#projectBtwVisibleText(messages: readonly AgentMessage[]): BtwRoleTextMessage[] {
+		const projected: BtwRoleTextMessage[] = [];
+		for (const message of messages) {
+			if (message.role !== "user" && message.role !== "assistant") continue;
+			const text = (
+				typeof message.content === "string"
+					? message.content
+					: message.content
+							.filter((block): block is TextContent => block.type === "text")
+							.map(block => block.text)
+							.join("")
+			).trim();
+			if (!text) continue;
+			projected.push({ role: message.role, text });
+		}
+		return projected;
+	}
+
+	#buildBtwAssistantMessage(text: string): AssistantMessage {
+		return {
+			role: "assistant",
+			content: [{ type: "text", text }],
+			api: "btw",
+			provider: "btw",
+			model: "btw",
+			usage: {
+				input: 0,
+				output: 0,
+				cacheRead: 0,
+				cacheWrite: 0,
+				totalTokens: 0,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+			},
+			stopReason: "stop",
+			timestamp: 0,
+		};
+	}
 	/**
-	 * Run a single ephemeral side-channel turn against this session's current
-	 * model + system prompt + history. No tools are used and session history is
-	 * not modified. Background turns retain the IRC/session behavior used by
-	 * autoreplies; `/btw` turns use an isolated committed-context policy.
+	 * Run a single ephemeral side-channel turn without modifying session history.
+	 * Background turns retain IRC/session behavior. `/btw` turns require a
+	 * pre-frozen, visible-text-only scope and bypass extension context transforms,
+	 * provider observability hooks, and session persistence surfaces.
 	 */
 	async runEphemeralTurn(args: EphemeralTurnArgs): Promise<EphemeralTurnResult> {
 		args.signal?.throwIfAborted();
-		const isBtw = args.purpose === "btw";
-		// `/btw` captures every provider-facing parent facet synchronously so an
-		// in-flight foreground mutation cannot create a mixed-generation request.
-		const btwSnapshot = isBtw
-			? this.#buildBtwEphemeralSnapshot(
-					cloneJsonValueForForkSeed(this.buildDisplaySessionContext().messages),
-					args.promptText,
-				)
-			: undefined;
-		const model = this.model;
-		const systemPrompt = isBtw ? [...this.systemPrompt] : undefined;
-		const thinkingLevel = this.thinkingLevel;
-		const hideThinkingSummary = this.agent.hideThinkingSummary;
-		const serviceTier = this.serviceTier;
-		const providerAffinitySessionId = this.agent.providerSessionId ?? this.agent.sessionId ?? this.sessionId;
-		const sideSessionId = isBtw ? `${providerAffinitySessionId}:btw:${crypto.randomUUID()}` : undefined;
-		const backgroundArgs = isBtw ? undefined : args;
-		const callerOwnsRosterClaim = backgroundArgs?.ircRosterClaim !== undefined;
-		const rosterClaim = isBtw
-			? null
-			: callerOwnsRosterClaim
-				? backgroundArgs?.ircRosterClaim
-				: this.#claimIrcRosterCandidate();
+		if (args.purpose === "btw") return await this.#runBtwTurn(args);
+
+		const callerOwnsRosterClaim = args.ircRosterClaim !== undefined;
+		const rosterClaim = callerOwnsRosterClaim ? args.ircRosterClaim : this.#claimIrcRosterCandidate();
 		const rosterClaimIsCurrent = () =>
 			!rosterClaim || this.#isCurrentIrcRosterClaim(rosterClaim.token, rosterClaim.epoch);
-		const prependMessagesValid = () => rosterClaimIsCurrent() && backgroundArgs?.prependMessagesValid?.() !== false;
+		const prependMessagesValid = () => rosterClaimIsCurrent() && args.prependMessagesValid?.() !== false;
 		const rosterMessage = !callerOwnsRosterClaim && rosterClaimIsCurrent() ? rosterClaim?.message : undefined;
 		try {
+			const model = this.model;
 			if (!model) throw new Error("No active model on session");
-			const credentialSessionId = isBtw ? providerAffinitySessionId : this.sessionId;
-			const apiKey = await awaitEphemeralAbort(
-				this.#modelRegistry.getApiKey(model, credentialSessionId),
-				args.signal,
-			);
+			const apiKey = await awaitEphemeralAbort(this.#modelRegistry.getApiKey(model, this.sessionId), args.signal);
 			if (!apiKey) throw new Error(`No API key for ${model.provider}/${model.id}`);
-
 			const prependMessages = prependMessagesValid()
-				? [...(rosterMessage ? [rosterMessage] : []), ...(backgroundArgs?.prependMessages ?? [])]
+				? [...(rosterMessage ? [rosterMessage] : []), ...(args.prependMessages ?? [])]
 				: undefined;
-			let snapshot = btwSnapshot ?? this.#buildEphemeralSnapshot(args.promptText, prependMessages);
+			let snapshot = this.#buildEphemeralSnapshot(args.promptText, prependMessages);
 			let llmMessages = await awaitEphemeralAbort(this.convertMessagesToLlm(snapshot, args.signal), args.signal);
-			if (!isBtw && prependMessages && !prependMessagesValid()) {
+			if (prependMessages && !prependMessagesValid()) {
 				snapshot = this.#buildEphemeralSnapshot(args.promptText);
 				llmMessages = await awaitEphemeralAbort(this.convertMessagesToLlm(snapshot, args.signal), args.signal);
 			}
-			const context: Context = {
-				systemPrompt: systemPrompt ?? this.systemPrompt,
-				messages: llmMessages,
-				tools: [],
-			};
-
+			const context: Context = { systemPrompt: this.systemPrompt, messages: llmMessages, tools: [] };
+			const ephemeralSessionId = crypto.randomUUID();
+			const options = this.prepareSimpleStreamOptions(
+				{
+					apiKey,
+					sessionId: ephemeralSessionId,
+					metadata: buildSessionMetadata(
+						ephemeralSessionId,
+						model.provider,
+						this.#modelRegistry.authStorage,
+						this.sessionId,
+					),
+					reasoning: toReasoningEffort(this.thinkingLevel),
+					hideThinkingSummary: this.agent.hideThinkingSummary,
+					serviceTier: this.serviceTier,
+					signal: args.signal,
+					toolChoice: "none",
+				},
+				model.provider,
+			);
+			args.signal?.throwIfAborted();
 			let replyText = "";
 			let assistantMessage: AssistantMessage | undefined;
-			if (isBtw) {
-				const establishmentAbort = new AbortController();
-				const requestSignal = args.signal
-					? AbortSignal.any([args.signal, establishmentAbort.signal])
-					: establishmentAbort.signal;
-				const timeoutError = new Error(
-					`/btw provider did not produce an event within ${BTW_ESTABLISHMENT_TIMEOUT_MS / 1000} seconds`,
-				);
-				timeoutError.name = "TimeoutError";
-				let establishmentTimer: NodeJS.Timeout | undefined;
-				try {
-					requestSignal.throwIfAborted();
-					const options: SimpleStreamOptions = {
-						apiKey,
-						sessionId: sideSessionId!,
-						metadata: buildSessionMetadata(
-							sideSessionId!,
-							model.provider,
-							this.#modelRegistry.authStorage,
-							providerAffinitySessionId,
-						),
-						reasoning: toReasoningEffort(thinkingLevel),
-						hideThinkingSummary,
-						serviceTier,
-						onPayload: this.#onPayload,
-						signal: requestSignal,
-						toolChoice: "none",
-						requestMaxRetries: 0,
-						streamMaxRetries: 0,
-						streamFirstEventTimeoutMs: 0,
-					};
-					establishmentTimer = setTimeout(
-						() => establishmentAbort.abort(timeoutError),
-						BTW_ESTABLISHMENT_TIMEOUT_MS,
-					);
-					establishmentTimer.unref?.();
-					const stream = streamSimple(model, context, options);
-					let receivedProviderEvent = false;
-					for await (const event of stream) {
-						if (!receivedProviderEvent && event.type !== "start") {
-							receivedProviderEvent = true;
-							clearTimeout(establishmentTimer);
-							establishmentTimer = undefined;
-						}
-						if (event.type === "text_delta") {
-							replyText += event.delta;
-							args.onTextDelta?.(event.delta);
-						} else if (event.type === "done") {
-							assistantMessage = event.message;
-							break;
-						} else if (event.type === "error") {
-							throw new Error(event.error.errorMessage || "Ephemeral turn failed");
-						}
-					}
-					requestSignal.throwIfAborted();
-				} catch (error) {
-					if (establishmentAbort.signal.aborted && !args.signal?.aborted) throw timeoutError;
-					throw error;
-				} finally {
-					if (establishmentTimer) clearTimeout(establishmentTimer);
-				}
-			} else {
-				const ephemeralSessionId = crypto.randomUUID();
-				const options = this.prepareSimpleStreamOptions(
-					{
-						apiKey,
-						sessionId: ephemeralSessionId,
-						metadata: buildSessionMetadata(
-							ephemeralSessionId,
-							model.provider,
-							this.#modelRegistry.authStorage,
-							this.sessionId,
-						),
-						reasoning: toReasoningEffort(thinkingLevel),
-						hideThinkingSummary,
-						serviceTier,
-						signal: args.signal,
-						toolChoice: "none",
-					},
-					model.provider,
-				);
-				args.signal?.throwIfAborted();
-				const stream = streamSimple(model, context, options);
-				for await (const event of stream) {
-					if (event.type === "text_delta") {
-						replyText += event.delta;
-						args.onTextDelta?.(event.delta);
-					} else if (event.type === "done") {
-						assistantMessage = event.message;
-						break;
-					} else if (event.type === "error") {
-						throw new Error(event.error.errorMessage || "Ephemeral turn failed");
-					}
+			for await (const event of streamSimple(model, context, options)) {
+				if (event.type === "text_delta") {
+					replyText += event.delta;
+					args.onTextDelta?.(event.delta);
+				} else if (event.type === "done") {
+					assistantMessage = event.message;
+					break;
+				} else if (event.type === "error") {
+					throw new Error(event.error.errorMessage || "Ephemeral turn failed");
 				}
 			}
-
 			if (!assistantMessage) throw new Error("Ephemeral turn ended without a final message");
 			args.signal?.throwIfAborted();
 			if (
-				!isBtw &&
 				!callerOwnsRosterClaim &&
 				rosterClaim &&
 				assistantMessage.stopReason !== "error" &&
@@ -14161,21 +14156,117 @@ export class AgentSession {
 			) {
 				this.#commitIrcRosterClaim(rosterClaim.token, rosterClaim.epoch);
 			}
-			args.signal?.throwIfAborted();
 			return { replyText: replyText.trim(), assistantMessage };
 		} finally {
-			if (!isBtw && !callerOwnsRosterClaim && rosterClaim) {
-				this.#releaseIrcRosterClaim(rosterClaim.token, rosterClaim.epoch);
+			if (!callerOwnsRosterClaim && rosterClaim) this.#releaseIrcRosterClaim(rosterClaim.token, rosterClaim.epoch);
+		}
+	}
+
+	async #runBtwTurn(args: Extract<EphemeralTurnArgs, { purpose: "btw" }>): Promise<EphemeralTurnResult> {
+		const model = args.turn.scope?.model;
+		const credentialSessionId = args.turn.scope?.credentialSessionId;
+		if (!model || !credentialSessionId) throw new Error("The /btw conversation scope was scrubbed.");
+		if (utf8ByteLength(args.turn.question) > BTW_MAX_QUESTION_UTF8_BYTES) {
+			throw new RangeError(`/btw questions are limited to ${BTW_MAX_QUESTION_UTF8_BYTES} UTF-8 bytes.`);
+		}
+		const apiKey = await awaitEphemeralAbort(this.#modelRegistry.getApiKey(model, credentialSessionId), args.signal);
+		if (!apiKey) throw new Error(`No API key for ${model.provider}/${model.id}`);
+		const scope = args.turn.scope;
+		if (!scope) throw new Error("The /btw conversation scope was scrubbed.");
+		const messages = scope.messages.map(message => ({
+			role: message.role,
+			content: [{ type: "text" as const, text: message.text }],
+		})) as Message[];
+		for (const exchange of boundBtwExchanges(args.contextExchanges ?? [])) {
+			messages.push({
+				role: "user",
+				content: [{ type: "text", text: exchange.question }],
+			} as Message);
+			messages.push({
+				role: "assistant",
+				content: [{ type: "text", text: exchange.answer }],
+			} as Message);
+		}
+		messages.push({
+			role: "user",
+			content: [{ type: "text", text: args.turn.question }],
+		} as Message);
+		const context: Context = { systemPrompt: scope.systemPrompt, messages, tools: [] };
+		const timeoutAbort = new AbortController();
+		const requestSignal = args.signal ? AbortSignal.any([args.signal, timeoutAbort.signal]) : timeoutAbort.signal;
+		const options: SimpleStreamOptions = {
+			apiKey,
+			sessionId: scope.sideSessionId,
+			reasoning: toReasoningEffort(scope.thinkingLevel),
+			hideThinkingSummary: scope.hideThinkingSummary,
+			serviceTier: scope.serviceTier,
+			signal: requestSignal,
+			toolChoice: "none",
+			requestMaxRetries: 0,
+			streamMaxRetries: 0,
+			streamFirstEventTimeoutMs: 0,
+		};
+		const iterator = streamSimple(scope.model, context, options)[Symbol.asyncIterator]();
+		let replyText = "";
+		let completed = false;
+		let active = true;
+		let onTextDelta = args.onTextDelta;
+		let idleTimer: NodeJS.Timeout | undefined;
+		const timeout = (message: string) => {
+			const error = new Error(message);
+			error.name = "TimeoutError";
+			timeoutAbort.abort(error);
+		};
+		const resetIdleTimer = () => {
+			if (idleTimer) clearTimeout(idleTimer);
+			idleTimer = setTimeout(
+				() => timeout(`/btw provider was idle for ${BTW_STREAM_IDLE_TIMEOUT_MS / 1000} seconds`),
+				BTW_STREAM_IDLE_TIMEOUT_MS,
+			);
+			idleTimer.unref?.();
+		};
+		const totalTimer = setTimeout(
+			() => timeout(`/btw provider exceeded ${BTW_STREAM_TOTAL_TIMEOUT_MS / 1000} seconds`),
+			BTW_STREAM_TOTAL_TIMEOUT_MS,
+		);
+		totalTimer.unref?.();
+		resetIdleTimer();
+		const consume = async () => {
+			while (active) {
+				const result = await iterator.next();
+				if (result.done || !active) break;
+				resetIdleTimer();
+				const event = result.value;
+				if (event.type === "text_delta") {
+					const bounded = truncateUtf8(replyText + event.delta, BTW_MAX_ANSWER_UTF8_BYTES);
+					const delta = bounded.slice(replyText.length);
+					replyText = bounded;
+					if (delta) onTextDelta?.(delta);
+				} else if (event.type === "done") {
+					completed = true;
+					break;
+				} else if (event.type === "error") {
+					throw new Error(event.error.errorMessage || "Ephemeral turn failed");
+				}
 			}
+		};
+		try {
+			await awaitEphemeralAbort(consume(), requestSignal);
+			requestSignal.throwIfAborted();
+			if (!completed) throw new Error("Ephemeral turn ended without a final message");
+			const finalText = replyText.trim();
+			return { replyText: finalText, assistantMessage: this.#buildBtwAssistantMessage(finalText) };
+		} finally {
+			active = false;
+			onTextDelta = undefined;
+			replyText = "";
+			context.messages = [];
+			if (idleTimer) clearTimeout(idleTimer);
+			clearTimeout(totalTimer);
+			void iterator.return?.().catch(() => undefined);
 		}
 	}
 
-	/** Build a `/btw` snapshot from an already-cloned committed context. */
-	#buildBtwEphemeralSnapshot(messages: AgentMessage[], promptText: string): AgentMessage[] {
-		messages.push(this.#buildEphemeralPromptMessage(promptText));
-		return messages;
-	}
-
 	/** Build a background snapshot with in-flight assistant and optional context. */
 	#buildEphemeralSnapshot(promptText: string, prependMessages?: AgentMessage[]): AgentMessage[] {
 		const messages = [...this.messages];