@valni/cli-darwin-x64 0.0.0-stage → 0.1.3

package/runtime/extensions/pi-switchboard/extensions/switchboard/envelope.ts

@@ -0,0 +1,199 @@
+import { EVENT_STREAM_CONTENT_TYPE, SENTINEL_SEGMENT } from "./constants.ts";
+import { resolveBaseUrl, resolveEndUserId, resolveSessionId } from "./config.ts";
+import { describeNetworkFailure, isAbortError, streamErrorResponse, translatedErrorResponse } from "./errors.ts";
+import { KIND_TO_API, type SwitchboardKind } from "./types.ts";
+
+const INFERENCE_PATH = "/v1/switchboard/inference";
+const SESSION_HEADER = "X-Switchboard-Session";
+const TOOL_ASK_HEADER = "X-Switchboard-Tool-Ask";
+const TOOL_ASK_STREAM_MARKER = ":switchboard.tool_ask ";
+const STEER_HEADER = "X-Switchboard-Steer";
+const STEER_STREAM_MARKER = ":switchboard.steer ";
+
+export type SteerDelivery = "steer" | "followUp";
+
+export type SteerSink = (steer: string, deliverAs: SteerDelivery) => void;
+
+let steerSink: SteerSink | null = null;
+
+export function onSteer(sink: SteerSink): void {
+	steerSink = sink;
+}
+
+export function deliverSteers(entries: unknown): void {
+	if (!Array.isArray(entries)) return;
+	for (const entry of entries) {
+		if (entry === null || typeof entry !== "object") continue;
+		const steer = (entry as { steer?: unknown }).steer;
+		if (typeof steer !== "string" || steer.length === 0) continue;
+		const deliverAs = (entry as { deliverAs?: unknown }).deliverAs === "steer" ? "steer" : "followUp";
+		steerSink?.(steer, deliverAs);
+	}
+}
+
+function recordSteerHeader(response: Response): void {
+	const header = response.headers.get(STEER_HEADER);
+	if (header === null) return;
+	try {
+		deliverSteers(JSON.parse(Buffer.from(header, "base64").toString("utf8")));
+	} catch (error) {
+		console.error("pi-switchboard: failed to parse the steer header", error);
+	}
+}
+
+function recordSteerMarkerLine(line: string): void {
+	if (!line.startsWith(STEER_STREAM_MARKER)) return;
+	try {
+		const parsed = JSON.parse(line.slice(STEER_STREAM_MARKER.length).trim()) as { steers?: unknown };
+		deliverSteers(parsed.steers);
+	} catch (error) {
+		console.error("pi-switchboard: failed to parse a steer stream marker", error);
+	}
+}
+
+export interface AskTag {
+	tool: string;
+	rule: string;
+	layer: string;
+}
+
+interface AskEntry {
+	id?: string;
+	tool: string;
+	rule: string;
+	layer: string;
+}
+
+const pendingAsks = new Map<string, AskTag>();
+
+export function consumePendingAsk(id: string): AskTag | undefined {
+	const ask = pendingAsks.get(id);
+	if (ask !== undefined) pendingAsks.delete(id);
+	return ask;
+}
+
+export function clearPendingAsks(): void {
+	pendingAsks.clear();
+}
+
+function recordAskEntries(entries: AskEntry[]): void {
+	for (const entry of entries) {
+		if (typeof entry.id !== "string") {
+			console.error("pi-switchboard: ignoring a tool-ask tag without a tool-call id; cannot correlate it to a tool call");
+			continue;
+		}
+		pendingAsks.set(entry.id, { tool: entry.tool, rule: entry.rule, layer: entry.layer });
+	}
+}
+
+function recordAskHeader(response: Response): void {
+	const header = response.headers.get(TOOL_ASK_HEADER);
+	if (header === null) return;
+	try {
+		const entries = JSON.parse(Buffer.from(header, "base64").toString("utf8")) as AskEntry[];
+		if (Array.isArray(entries)) recordAskEntries(entries);
+	} catch (error) {
+		console.error("pi-switchboard: failed to parse the tool-ask header", error);
+	}
+}
+
+function recordAskMarkerLine(line: string): void {
+	if (!line.startsWith(TOOL_ASK_STREAM_MARKER)) return;
+	try {
+		const parsed = JSON.parse(line.slice(TOOL_ASK_STREAM_MARKER.length).trim()) as { asks?: AskEntry[] };
+		if (Array.isArray(parsed.asks)) recordAskEntries(parsed.asks);
+	} catch (error) {
+		console.error("pi-switchboard: failed to parse a tool-ask stream marker", error);
+	}
+}
+
+function scanMarkerLine(line: string): void {
+	recordAskMarkerLine(line);
+	recordSteerMarkerLine(line);
+}
+
+function scanResponseStream(response: Response): Response {
+	if (response.body === null) return response;
+	const decoder = new TextDecoder();
+	let buffer = "";
+	const scanner = new TransformStream<Uint8Array, Uint8Array>({
+		transform(chunk, controller) {
+			controller.enqueue(chunk);
+			buffer += decoder.decode(chunk, { stream: true });
+			let newlineIndex = buffer.indexOf("\n");
+			while (newlineIndex !== -1) {
+				scanMarkerLine(buffer.slice(0, newlineIndex));
+				buffer = buffer.slice(newlineIndex + 1);
+				newlineIndex = buffer.indexOf("\n");
+			}
+		},
+		flush() {
+			buffer += decoder.decode();
+			scanMarkerLine(buffer);
+		},
+	});
+	return new Response(response.body.pipeThrough(scanner), {
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers,
+	});
+}
+
+function captureResponseSignals(response: Response): Response {
+	recordAskHeader(response);
+	recordSteerHeader(response);
+	if ((response.headers.get("content-type") ?? "").includes(EVENT_STREAM_CONTENT_TYPE)) {
+		return scanResponseStream(response);
+	}
+	return response;
+}
+
+function isEnvelopeTarget(url: string): SwitchboardKind | null {
+	const sentinelIndex = url.indexOf(SENTINEL_SEGMENT);
+	if (sentinelIndex === -1) return null;
+	const kindTag = url.slice(sentinelIndex + SENTINEL_SEGMENT.length).split("/")[0];
+	return kindTag in KIND_TO_API ? (kindTag as SwitchboardKind) : null;
+}
+
+let envelopeFetchInstalled = false;
+
+export function installEnvelopeFetch(): void {
+	if (envelopeFetchInstalled) return;
+	envelopeFetchInstalled = true;
+	const baseFetch = globalThis.fetch.bind(globalThis);
+	globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+		const url = input instanceof Request ? input.url : input.toString();
+		const kindTag = isEnvelopeTarget(url);
+		if (kindTag === null) return baseFetch(input, init);
+		const request = new Request(input, init);
+		const nativeBody = (await request.json()) as Record<string, unknown>;
+		const headers = new Headers(request.headers);
+		headers.set("Content-Type", "application/json");
+		const anthropicStyleKey = headers.get("x-api-key");
+		if (!headers.has("Authorization") && anthropicStyleKey) {
+			headers.set("Authorization", `Bearer ${anthropicStyleKey}`);
+			headers.delete("x-api-key");
+		}
+		const sessionId = resolveSessionId();
+		if (sessionId !== null) headers.set(SESSION_HEADER, sessionId);
+		let response: Response;
+		try {
+			response = await baseFetch(`${resolveBaseUrl()}${INFERENCE_PATH}`, {
+				method: "POST",
+				headers,
+				body: JSON.stringify({
+					user_id: resolveEndUserId(),
+					time: new Date().toISOString(),
+					idempotency_key: crypto.randomUUID(),
+					kind: { [kindTag]: nativeBody },
+				}),
+				signal: request.signal,
+			});
+		} catch (error) {
+			if (isAbortError(error)) throw error;
+			return streamErrorResponse(kindTag, describeNetworkFailure(error));
+		}
+		if (response.ok) return captureResponseSignals(response);
+		return translatedErrorResponse(kindTag, response);
+	};
+}

package/runtime/extensions/pi-switchboard/extensions/switchboard/errors.ts

@@ -0,0 +1,180 @@
+import { EVENT_STREAM_CONTENT_TYPE } from "./constants.ts";
+import { resolveBaseUrl } from "./config.ts";
+import type { SwitchboardKind } from "./types.ts";
+
+const PORTAL_URL = "https://valni.app/platform";
+const ERROR_DETAIL_LIMIT = 300;
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]+/g;
+const PROVIDER_TROUBLE_MESSAGE = "The model provider is having trouble. Retry shortly, or switch to a different model.";
+const TRANSIENT_PROVIDER_CODES = new Set(["SWB-5105", "SWB-5204", "SWB-5205", "SWB-5206"]);
+
+export interface SwitchboardErrorEnvelope {
+	code?: string;
+	error?: string;
+	fault?: string;
+	requestId?: string;
+	detail?: string;
+	upstreamStatus?: number;
+	requestedMaxTokens?: number;
+	maxOutputTokens?: number;
+}
+
+function displayableDetail(text: string): string {
+	return singleLine(text.replace(CONTROL_CHARACTERS, " ")).slice(0, ERROR_DETAIL_LIMIT);
+}
+
+function upstreamDetail(envelope: SwitchboardErrorEnvelope): string {
+	if (typeof envelope.detail !== "string") return "";
+	const trimmed = envelope.detail.trim();
+	if (!trimmed) return "";
+	if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+		try {
+			const parsed = JSON.parse(trimmed) as { error?: { message?: unknown } };
+			const message = parsed.error?.message;
+			if (typeof message === "string" && message.trim()) return displayableDetail(message);
+		} catch {
+		}
+	}
+	return displayableDetail(trimmed);
+}
+
+function switchboardGuidance(envelope: SwitchboardErrorEnvelope & { code: string; error: string }): string {
+	switch (envelope.code) {
+		case "SWB-1001":
+			return `Wrong application key. Log in to Switchboard at ${PORTAL_URL} and get a key, then set your application key and restart pi.`;
+		case "SWB-1013":
+			return "Your Switchboard session expired. Run /login to sign in again.";
+		case "SWB-1014":
+			return "Your Switchboard session is invalid. Run /login to sign in again.";
+		case "SWB-1007":
+			return `Out of Switchboard credit. Top up at ${PORTAL_URL} and retry.`;
+		case "SWB-1003":
+		case "SWB-1004":
+		case "SWB-1008":
+			return "Over your rate limit. Wait a moment and retry, or raise the limit in the portal.";
+		case "SWB-1005":
+		case "SWB-1009":
+		case "SWB-1011":
+			return "A spend limit on this account was reached. Raise it in the portal to continue.";
+		case "SWB-1010":
+		case "SWB-1012":
+			return "This model is not enabled for this account. Switch models, or enable it in the portal.";
+		case "SWB-1025":
+			return `This model runs on your own provider subscription, which is not connected to Switchboard yet. Connect it at ${PORTAL_URL}/switchboard#connections, then retry.`;
+		case "SWB-1026":
+			return `Your provider subscription connection to Switchboard expired. Reconnect it at ${PORTAL_URL}/switchboard#connections, then retry.`;
+		case "SWB-1301":
+			return "Company policy denied this tool call. Change the policy in the portal, or ask the agent for a different approach.";
+		case "SWB-2005":
+		case "SWB-2006":
+		case "SWB-2007":
+			return "Your end user id is not registered on this account. Fix the end user id or register it in the portal, then restart pi.";
+		case "SWB-2008":
+			return `This end user is disabled on the account. Re-enable it at ${PORTAL_URL} to continue.`;
+		case "SWB-2048":
+			return typeof envelope.maxOutputTokens === "number" && typeof envelope.requestedMaxTokens === "number"
+				? `This model accepts at most ${envelope.maxOutputTokens} output tokens and the request asked for ${envelope.requestedMaxTokens}. Lower max_tokens and retry.`
+				: "The request asked for more output tokens than this model allows. Lower max_tokens and retry.";
+		case "SWB-3001":
+		case "SWB-3005":
+			return "This model is no longer available in the catalog. Pick a different model.";
+		case "SWB-5207":
+			return "The provider account behind Switchboard is out of credit. Retrying will not help — the account needs topping up.";
+		case "SWB-5208": {
+			const rejection = upstreamDetail(envelope);
+			return rejection
+				? `The provider rejected the request Switchboard sent: ${rejection}. Retrying the same request will not help.`
+				: "The provider rejected the request Switchboard sent. Retrying the same request will not help; report the reference.";
+		}
+		case "SWB-5002":
+		case "SWB-5003":
+		case "SWB-5101":
+		case "SWB-5102":
+		case "SWB-5103":
+		case "SWB-5108":
+		case "SWB-5202":
+			return "This model is not available on Switchboard right now. Pick a different model, and report the reference if it keeps happening.";
+	}
+	if (envelope.fault === "provider") {
+		const detail = upstreamDetail(envelope);
+		if (!detail) return PROVIDER_TROUBLE_MESSAGE;
+		return TRANSIENT_PROVIDER_CODES.has(envelope.code)
+			? `The model provider is having trouble: ${detail}. Retry shortly, or switch to a different model.`
+			: `The model provider returned an error: ${detail}`;
+	}
+	if (envelope.fault === "client") {
+		return `Switchboard rejected the request: ${envelope.error}.`;
+	}
+	return "Switchboard hit an internal problem. Not your fault. Retry shortly, and report the request id if it keeps happening.";
+}
+
+function referenceCode(envelope: SwitchboardErrorEnvelope & { code: string }): string {
+	return typeof envelope.upstreamStatus === "number" ? `${envelope.code}(${envelope.upstreamStatus})` : envelope.code;
+}
+
+function userFacingMessage(envelope: SwitchboardErrorEnvelope & { code: string; error: string }, status: number): string {
+	const code = referenceCode(envelope);
+	const reference = envelope.requestId ? `${code}, request ${envelope.requestId}` : `${code}, HTTP ${status}`;
+	return `${switchboardGuidance(envelope)} [${reference}]`;
+}
+
+function unexpectedResponseMessage(response: Response, text: string): string {
+	console.error(`pi-switchboard: unexpected Switchboard response (HTTP ${response.status}): ${text.slice(0, ERROR_DETAIL_LIMIT)}`);
+	return `Switchboard returned an unexpected response (HTTP ${response.status}). Retry shortly, and report it if it keeps happening.`;
+}
+
+export async function describeFailure(response: Response): Promise<string> {
+	const text = await response.text();
+	let envelope: SwitchboardErrorEnvelope;
+	try {
+		envelope = JSON.parse(text) as SwitchboardErrorEnvelope;
+	} catch {
+		return unexpectedResponseMessage(response, text);
+	}
+	if (!envelope.code || !envelope.error) {
+		return unexpectedResponseMessage(response, text);
+	}
+	return userFacingMessage({ ...envelope, code: envelope.code, error: envelope.error }, response.status);
+}
+
+export function isAbortError(error: unknown): boolean {
+	return error instanceof Error && error.name === "AbortError";
+}
+
+export function singleLine(message: string): string {
+	return message.replace(/\s+/g, " ").trim();
+}
+
+export function streamErrorResponse(kindTag: SwitchboardKind, message: string): Response {
+	const clean = singleLine(message);
+	const stream =
+		kindTag === "anthropic"
+			? `event: error\ndata: ${clean}\n\n`
+			: `data: ${JSON.stringify({ error: { message: clean, type: "api_error" } })}\n\n`;
+	return new Response(stream, {
+		status: 200,
+		headers: { "Content-Type": EVENT_STREAM_CONTENT_TYPE },
+	});
+}
+
+export async function translatedErrorResponse(kindTag: SwitchboardKind, response: Response): Promise<Response> {
+	return streamErrorResponse(kindTag, await describeFailure(response));
+}
+
+export function describeNetworkFailure(error: unknown): string {
+	let location = "";
+	try {
+		const host = new URL(resolveBaseUrl()).host;
+		if (host) location = ` at ${host}`;
+	} catch {
+	}
+	if (error instanceof Error && error.name === "TimeoutError") {
+		return `Can't reach Switchboard${location}: it took too long to respond. Check your connection and try again.`;
+	}
+	const cause = (error as { cause?: { code?: string } }).cause;
+	const code = cause?.code ?? (error as { code?: string }).code;
+	if (code === "ECONNREFUSED") {
+		return `Can't reach Switchboard${location}: the connection was refused. It may be down. Try again in a moment.`;
+	}
+	return `Can't reach Switchboard${location}. Check your internet connection and try again.`;
+}

package/runtime/extensions/pi-switchboard/extensions/switchboard/index.ts

@@ -0,0 +1,125 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ModelsStoreEntry, OAuthCredentials, RefreshModelsContext } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { buildModelConfigs, credentialBearer, discoverCatalog, loadRegistryModels } from "./catalog.ts";
+import {
+	clearSessionCredentials,
+	clearSessionId,
+	rememberSessionCredentials,
+	resolveBaseUrl,
+	setSessionEndUserId,
+	setSessionId,
+} from "./config.ts";
+import { MILLISECONDS_PER_SECOND, PROVIDER_ID, spawnedConnectionId } from "./constants.ts";
+import { switchboardLogin } from "./connections.ts";
+import { deviceRefresh } from "./device-auth.ts";
+import { clearPendingAsks, consumePendingAsk, installEnvelopeFetch, onSteer } from "./envelope.ts";
+import { startSessionStream, stopSessionStream } from "./sessionStream.ts";
+import { registerParticipantFraming } from "./participant.ts";
+import { discoverTools } from "./toolProxy.ts";
+import { registerServerTools } from "./tools.ts";
+
+const PROVIDER_NAME = "Switchboard";
+const APPROVAL_DIALOG_TITLE = "Switchboard approval required";
+
+function extensionVersion(): string {
+	try {
+		const packagePath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+		return (JSON.parse(readFileSync(packagePath, "utf8")) as { version: string }).version;
+	} catch {
+		return "unknown";
+	}
+}
+
+export default async function (pi: ExtensionAPI) {
+	console.error(`pi-switchboard v${extensionVersion()}`);
+	const baseUrl = resolveBaseUrl();
+	const registry = await loadRegistryModels();
+	const environmentKey = process.env.SWITCHBOARD_API_KEY;
+	let startupModels: ReturnType<typeof buildModelConfigs> = [];
+	if (environmentKey) {
+		const [catalog, tools] = await Promise.allSettled([
+			discoverCatalog(baseUrl, environmentKey),
+			discoverTools(baseUrl, environmentKey),
+		]);
+		if (catalog.status === "rejected") throw catalog.reason;
+		startupModels = buildModelConfigs(catalog.value, registry);
+		if (tools.status === "fulfilled") {
+			registerServerTools(pi, tools.value);
+		} else {
+			console.error("pi-switchboard: server tool discovery failed for key mode", tools.reason);
+		}
+	}
+	installEnvelopeFetch();
+	registerParticipantFraming(pi);
+	onSteer((steer, deliverAs) => {
+		pi.sendUserMessage(steer, { deliverAs });
+	});
+	pi.on("session_start", (_event, ctx) => {
+		setSessionId(spawnedConnectionId() ?? ctx.sessionManager.getSessionId());
+		startSessionStream(ctx);
+	});
+	pi.on("tool_call", async (event, ctx) => {
+		const ask = consumePendingAsk(event.toolCallId);
+		if (ask === undefined) return;
+		const policy = `Switchboard ${ask.layer} policy requires approval for ${ask.rule}`;
+		if (!ctx.hasUI) {
+			return { block: true, reason: `${policy}; denied in a non-interactive session (no human to approve)` };
+		}
+		const approved = await ctx.ui.confirm(
+			APPROVAL_DIALOG_TITLE,
+			`The agent wants to run ${event.toolName}.\n\n${policy}. Allow this call?`,
+		);
+		if (!approved) return { block: true, reason: `Declined: ${policy}` };
+		return;
+	});
+	pi.on("session_shutdown", () => {
+		clearPendingAsks();
+		stopSessionStream();
+		clearSessionId();
+		clearSessionCredentials();
+	});
+	pi.registerProvider(PROVIDER_ID, {
+		name: PROVIDER_NAME,
+		baseUrl,
+		apiKey: "$SWITCHBOARD_API_KEY",
+		oauth: {
+			name: "Switchboard",
+			login: switchboardLogin,
+			refreshToken: deviceRefresh,
+			getApiKey: (credentials: OAuthCredentials) => {
+				if (typeof credentials.endUserId === "string") setSessionEndUserId(credentials.endUserId);
+				rememberSessionCredentials(credentials);
+				return credentials.access;
+			},
+		},
+		models: startupModels,
+		refreshModels: async (context: RefreshModelsContext) => {
+			const bearer = credentialBearer(context.credential);
+			if (!bearer) {
+				await context.store.delete();
+				return [];
+			}
+			const stored = await context.store.read();
+			if (!context.allowNetwork) {
+				return stored ? ([...stored.models] as ReturnType<typeof buildModelConfigs>) : startupModels;
+			}
+			const catalog = await discoverCatalog(baseUrl, bearer);
+			const configs = buildModelConfigs(catalog, registry);
+			await context.store.write({
+				models: configs as unknown as ModelsStoreEntry["models"],
+				checkedAt: Math.floor(Date.now() / MILLISECONDS_PER_SECOND),
+			});
+			if (context.credential?.type === "oauth") {
+				try {
+					registerServerTools(pi, await discoverTools(baseUrl, bearer));
+				} catch (error) {
+					console.error("pi-switchboard: server tool discovery failed", error);
+				}
+			}
+			return configs;
+		},
+	});
+}

package/runtime/extensions/pi-switchboard/extensions/switchboard/participant.ts

@@ -0,0 +1,17 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { spawnedConnectionId } from "./constants.ts";
+
+export const PARTICIPANT_FRAMING =
+	"You are a participant on a live automation connection, not a solo task. Your text output is not delivered to anyone — the only way to reach the other participant is the send_message tool: set expects_response true if you are waiting on a reply, false if you have nothing pending. The connection stays open and you stay available between messages — after you reply, wait for the other participant's next message. When the work is finished, call close_automation_connection to end it; nothing more is expected of you. Do your own work and reply here — do not open_automation_connection unless the task explicitly asks you to bring in a separate automation. The connection_id is filled in for you — you never type it.";
+
+export function composeParticipantSystemPrompt(existing: string | undefined): string {
+	if (existing === undefined || existing.trim() === "") return PARTICIPANT_FRAMING;
+	return `${existing}\n\n${PARTICIPANT_FRAMING}`;
+}
+
+export function registerParticipantFraming(pi: ExtensionAPI): void {
+	if (spawnedConnectionId() === null) return;
+	pi.on("before_agent_start", event => ({
+		systemPrompt: composeParticipantSystemPrompt(event.systemPrompt),
+	}));
+}

package/runtime/extensions/pi-switchboard/extensions/switchboard/sessionStream.ts

@@ -0,0 +1,131 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolveBaseUrl, resolveSessionId } from "./config.ts";
+import { PROVIDER_ID, spawnedConnectionId } from "./constants.ts";
+import { deliverSteers } from "./envelope.ts";
+
+const KEY_ENV = "SWITCHBOARD_API_KEY";
+
+const STREAM_PATH = "/v1/switchboard/session-stream";
+const SESSION_QUERY_PARAMETER = "session";
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_CAP_MS = 60_000;
+const STREAMING_MODES = new Set(["tui", "rpc"]);
+
+let activeSocket: WebSocket | null = null;
+let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+let reconnectAttempt = 0;
+let stopped = true;
+
+function streamUrl(sessionId: string): string {
+	const url = new URL(`${resolveBaseUrl()}${STREAM_PATH}`);
+	if (url.protocol === "https:") url.protocol = "wss:";
+	else if (url.protocol === "http:") url.protocol = "ws:";
+	url.searchParams.set(SESSION_QUERY_PARAMETER, sessionId);
+	return url.toString();
+}
+
+export function spawnedStreamKey(connectionId: string | null, envKey: string | undefined): string | null {
+	if (connectionId === null) return null;
+	const key = envKey?.trim();
+	return key ? key : null;
+}
+
+async function resolveStreamToken(context: ExtensionContext): Promise<string | null> {
+	const connectionId = spawnedConnectionId();
+	if (connectionId !== null) return spawnedStreamKey(connectionId, process.env[KEY_ENV]);
+	let resolution: Awaited<ReturnType<ExtensionContext["modelRegistry"]["getProviderAuth"]>>;
+	try {
+		resolution = await context.modelRegistry.getProviderAuth(PROVIDER_ID);
+	} catch {
+		return null;
+	}
+	if (resolution?.source !== "OAuth") return null;
+	return resolution.auth.apiKey ?? null;
+}
+
+function scheduleReconnect(context: ExtensionContext): void {
+	if (stopped || reconnectTimer !== null) return;
+	const backoff = Math.min(RECONNECT_BASE_MS * 2 ** reconnectAttempt, RECONNECT_CAP_MS);
+	const delay = backoff / 2 + Math.random() * (backoff / 2);
+	reconnectAttempt += 1;
+	reconnectTimer = setTimeout(() => {
+		reconnectTimer = null;
+		void connect(context);
+	}, delay);
+	reconnectTimer.unref?.();
+}
+
+function handleFrame(raw: unknown): void {
+	if (typeof raw !== "string") return;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return;
+	}
+	if (parsed === null || typeof parsed !== "object") return;
+	if ((parsed as { type?: unknown }).type !== "steer") return;
+	deliverSteers([parsed]);
+}
+
+async function connect(context: ExtensionContext): Promise<void> {
+	if (stopped || activeSocket !== null) return;
+	const sessionId = resolveSessionId();
+	if (sessionId === null) return scheduleReconnect(context);
+	const token = await resolveStreamToken(context);
+	if (token === null) return scheduleReconnect(context);
+
+	let socket: WebSocket;
+	try {
+		socket = new WebSocket(streamUrl(sessionId));
+	} catch {
+		return scheduleReconnect(context);
+	}
+	activeSocket = socket;
+
+	socket.addEventListener("open", () => {
+		socket.send(JSON.stringify({ type: "auth", token, session: sessionId }));
+		reconnectAttempt = 0;
+	});
+	socket.addEventListener("message", (event: MessageEvent) => {
+		handleFrame(event.data);
+	});
+	socket.addEventListener("close", () => {
+		if (activeSocket === socket) activeSocket = null;
+		scheduleReconnect(context);
+	});
+	socket.addEventListener("error", () => {
+		if (activeSocket === socket) activeSocket = null;
+		try {
+			socket.close();
+		} catch {
+			void 0;
+		}
+		scheduleReconnect(context);
+	});
+}
+
+export function startSessionStream(context: ExtensionContext): void {
+	if (!STREAMING_MODES.has(context.mode)) return;
+	stopSessionStream();
+	stopped = false;
+	void connect(context);
+}
+
+export function stopSessionStream(): void {
+	stopped = true;
+	reconnectAttempt = 0;
+	if (reconnectTimer !== null) {
+		clearTimeout(reconnectTimer);
+		reconnectTimer = null;
+	}
+	const socket = activeSocket;
+	activeSocket = null;
+	if (socket !== null) {
+		try {
+			socket.close();
+		} catch {
+			return;
+		}
+	}
+}