@p8n.ai/pi-listens 0.1.0

package/src/config.ts

@@ -0,0 +1,182 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+
+export type SttMode = "transcribe" | "translate" | "verbatim" | "translit" | "codemix";
+export type RecordMode = "utterance" | "fixed";
+
+export interface PiListensConfig {
+	apiKey?: string;
+	sttModel: string;
+	sttMode: SttMode;
+	sttLanguageCode: string;
+	translateInputToEnglish: boolean;
+	ttsModel: string;
+	ttsLanguageCode: string;
+	ttsSpeaker: string;
+	ttsPace?: number;
+	ttsTemperature?: number;
+	ttsSampleRate: number;
+	ttsOutputCodec: "wav" | "mp3" | "linear16" | "mulaw" | "alaw" | "opus" | "flac" | "aac";
+	recordSeconds: number;
+	recordSampleRate: number;
+	recordMode: RecordMode;
+	silenceStartSeconds: number;
+	silenceStopSeconds: number;
+	silenceThreshold: string;
+	recordCommand?: string;
+	playCommand?: string;
+	streamCommand?: string;
+	streamChunkMs: number;
+	streamMaxSeconds: number;
+	audioDir: string;
+	deleteAudio: boolean;
+	textFallback: boolean;
+	autoSpeakAssistant: boolean;
+	maxAutoSpeakChars: number;
+}
+
+const DEFAULT_CONFIG: PiListensConfig = {
+	sttModel: "saaras:v3",
+	sttMode: "transcribe",
+	sttLanguageCode: "unknown",
+	translateInputToEnglish: true,
+	ttsModel: "bulbul:v3",
+	ttsLanguageCode: "en-IN",
+	ttsSpeaker: "shubh",
+	ttsPace: 1,
+	ttsTemperature: 0.6,
+	ttsSampleRate: 24000,
+	ttsOutputCodec: "wav",
+	recordSeconds: 300,
+	recordSampleRate: 16000,
+	streamChunkMs: 250,
+	streamMaxSeconds: 300,
+	recordMode: "utterance",
+	silenceStartSeconds: 0.2,
+	silenceStopSeconds: 3.5,
+	silenceThreshold: "1%",
+	audioDir: join(tmpdir(), "pi-listens"),
+	deleteAudio: true,
+	textFallback: true,
+	autoSpeakAssistant: false,
+	maxAutoSpeakChars: 900,
+};
+
+type RawConfig = Partial<PiListensConfig>;
+
+export function resolveConfig(cwd: string): PiListensConfig {
+	const legacyUserPath = join(homedir(), ".pi", "agent", "pi-listens.json");
+	const userPath = join(homedir(), ".pi", "pi-listens.json");
+	const projectPath = join(cwd, ".pi", "pi-listens.json");
+	const fileConfig = {
+		...readJson(legacyUserPath),
+		...readJson(userPath),
+		...readJson(projectPath),
+	};
+
+	const envConfig: RawConfig = {
+		apiKey: env("SARVAM_API_KEY") ?? env("SARVAM_API_SUBSCRIPTION_KEY") ?? env("PI_LISTENS_SARVAM_API_KEY"),
+		sttModel: env("PI_LISTENS_STT_MODEL"),
+		sttMode: parseSttMode(env("PI_LISTENS_STT_MODE")),
+		sttLanguageCode: env("PI_LISTENS_STT_LANGUAGE"),
+		translateInputToEnglish: parseBoolean(env("PI_LISTENS_TRANSLATE_INPUT_TO_ENGLISH")),
+		ttsModel: env("PI_LISTENS_TTS_MODEL"),
+		ttsLanguageCode: env("PI_LISTENS_TTS_LANGUAGE"),
+		ttsSpeaker: env("PI_LISTENS_TTS_SPEAKER"),
+		ttsPace: parseNumber(env("PI_LISTENS_TTS_PACE")),
+		ttsTemperature: parseNumber(env("PI_LISTENS_TTS_TEMPERATURE")),
+		ttsSampleRate: parseInteger(env("PI_LISTENS_TTS_SAMPLE_RATE")),
+		ttsOutputCodec: parseCodec(env("PI_LISTENS_TTS_OUTPUT_CODEC")),
+		recordSeconds: parseInteger(env("PI_LISTENS_RECORD_SECONDS")),
+		recordSampleRate: parseInteger(env("PI_LISTENS_RECORD_SAMPLE_RATE")),
+		recordMode: parseRecordMode(env("PI_LISTENS_RECORD_MODE")),
+		silenceStartSeconds: parseNumber(env("PI_LISTENS_SILENCE_START_SECONDS")),
+		silenceStopSeconds: parseNumber(env("PI_LISTENS_SILENCE_STOP_SECONDS")),
+		silenceThreshold: env("PI_LISTENS_SILENCE_THRESHOLD"),
+		recordCommand: env("PI_LISTENS_RECORD_COMMAND"),
+		playCommand: env("PI_LISTENS_PLAY_COMMAND"),
+		streamCommand: env("PI_LISTENS_STREAM_COMMAND"),
+		streamChunkMs: parseInteger(env("PI_LISTENS_STREAM_CHUNK_MS")),
+		streamMaxSeconds: parseInteger(env("PI_LISTENS_STREAM_MAX_SECONDS")),
+		audioDir: env("PI_LISTENS_AUDIO_DIR"),
+		deleteAudio: parseBoolean(env("PI_LISTENS_DELETE_AUDIO")),
+		textFallback: parseBoolean(env("PI_LISTENS_TEXT_FALLBACK")),
+		autoSpeakAssistant: parseBoolean(env("PI_LISTENS_AUTO_SPEAK")),
+		maxAutoSpeakChars: parseInteger(env("PI_LISTENS_MAX_AUTO_SPEAK_CHARS")),
+	};
+
+	return mergeDefined(DEFAULT_CONFIG, fileConfig, envConfig);
+}
+
+function readJson(path: string): RawConfig {
+	if (!existsSync(path)) return {};
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as RawConfig;
+		return parsed && typeof parsed === "object" ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+
+function env(name: string): string | undefined {
+	const value = process.env[name];
+	return value && value.trim() ? value.trim() : undefined;
+}
+
+function parseBoolean(value: string | undefined): boolean | undefined {
+	if (value === undefined) return undefined;
+	if (["1", "true", "yes", "on"].includes(value.toLowerCase())) return true;
+	if (["0", "false", "no", "off"].includes(value.toLowerCase())) return false;
+	return undefined;
+}
+
+function parseInteger(value: string | undefined): number | undefined {
+	if (value === undefined) return undefined;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function parseNumber(value: string | undefined): number | undefined {
+	if (value === undefined) return undefined;
+	const parsed = Number.parseFloat(value);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function parseSttMode(value: string | undefined): SttMode | undefined {
+	if (!value) return undefined;
+	const allowed = new Set(["transcribe", "translate", "verbatim", "translit", "codemix"]);
+	return allowed.has(value) ? (value as SttMode) : undefined;
+}
+
+function parseRecordMode(value: string | undefined): RecordMode | undefined {
+	if (!value) return undefined;
+	return value === "utterance" || value === "fixed" ? value : undefined;
+}
+
+function parseCodec(value: string | undefined): PiListensConfig["ttsOutputCodec"] | undefined {
+	if (!value) return undefined;
+	const allowed = new Set(["wav", "mp3", "linear16", "mulaw", "alaw", "opus", "flac", "aac"]);
+	return allowed.has(value) ? (value as PiListensConfig["ttsOutputCodec"]) : undefined;
+}
+
+function mergeDefined(...configs: RawConfig[]): PiListensConfig {
+	const merged: Record<string, unknown> = {};
+	for (const config of configs) {
+		for (const [key, value] of Object.entries(config)) {
+			if (value !== undefined) merged[key] = value;
+		}
+	}
+	return merged as unknown as PiListensConfig;
+}
+
+export function maskSecret(value: string | undefined): string {
+	if (!value) return "not set";
+	if (value.length <= 8) return "set";
+	return `${value.slice(0, 4)}…${value.slice(-4)}`;
+}
+
+export function audioExtensionForCodec(codec: PiListensConfig["ttsOutputCodec"]): string {
+	if (codec === "linear16" || codec === "mulaw" || codec === "alaw") return "raw";
+	return codec;
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createAudioRuntime, type AudioRuntime } from "./audio.js";
+import { maskSecret, resolveConfig, type PiListensConfig } from "./config.js";
+import { SarvamSpeechClient } from "./sarvam.js";
+import { attachStateToServices, maybeContinueVoiceLoop, registerVoiceCommands, stopVoiceMode, type VoiceModeState } from "./commands.js";
+import { registerVoiceTools, type VoiceToolServices } from "./tools.js";
+import { firstTextContent } from "./text.js";
+
+export default function piListensExtension(pi: ExtensionAPI) {
+	let config: PiListensConfig = resolveConfig(process.cwd());
+	let audio: AudioRuntime = createAudioRuntime(config);
+	let lastCwd = process.cwd();
+
+	const speech = new SarvamSpeechClient(() => config);
+	const state: VoiceModeState = {
+
+		enabled: false,
+		autoListen: false,
+		autoSpeakAssistant: config.autoSpeakAssistant,
+		isListening: false,
+		status: "idle",
+		recordSeconds: config.recordSeconds,
+		silenceStopSeconds: config.silenceStopSeconds,
+	};
+
+	const services: VoiceToolServices = {
+		getConfig: () => config,
+		getAudio: () => audio,
+		getSpeech: () => speech,
+	};
+	attachStateToServices(services, state);
+
+	function reloadConfig(cwd: string) {
+		lastCwd = cwd;
+		config = resolveConfig(cwd);
+		audio = createAudioRuntime(config);
+		if (!state.enabled) { state.autoSpeakAssistant = config.autoSpeakAssistant; state.recordSeconds = config.recordSeconds; state.silenceStopSeconds = config.silenceStopSeconds; }
+	}
+
+	registerVoiceTools(pi, services);
+	registerVoiceCommands(pi, services, state);
+
+	pi.on("session_start", async (_event, ctx) => {
+		reloadConfig(ctx.cwd);
+		const audioInfo = audio.describe();
+		const ready = Boolean(config.apiKey) && audioInfo.recorder !== "missing" && audioInfo.player !== "missing";
+		ctx.ui.setStatus("pi-listens", state.enabled ? "voice on" : ready ? "voice ready" : "voice setup needed");
+		if (!ready) {
+			ctx.ui.notify(
+				[
+					"pi-listens is loaded but not fully ready.",
+					`Sarvam API key: ${maskSecret(config.apiKey)}`,
+					`Recorder: ${audioInfo.recorder}`,
+					`Player: ${audioInfo.player}`,
+					"Run /voice-status or call voice_setup_check for details.",
+				].join("\n"),
+				"warning",
+			);
+		}
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		stopVoiceMode(services, state, ctx);
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		return {
+			systemPrompt: `${event.systemPrompt}\n\nPi Listens voice guidance:\n- The user may primarily interact by speech through Sarvam AI. Text input is still possible.\n- When voice mode is active, treat it as a hands-free conversation: listen only while the voice UI/input tool is active, then pause listening while you work.\n- Use voice_output for concise spoken progress, completion, or status updates that matter to the user.\n- When you need clarification, confirmation, or any user input, prefer voice_ask with a concise spoken question instead of asking only in text.\n- Use voice_input only after the user already knows you are listening.\n- Do not speak code blocks, logs, diffs, stack traces, or long explanations; summarize them briefly and leave detail in text.`,
+		};
+	});
+
+	pi.on("message_end", async (event) => {
+		if (event.message.role !== "assistant") return;
+		state.lastAssistantText = firstTextContent(event.message);
+	});
+
+	pi.on("agent_end", async (_event, ctx) => {
+		await maybeContinueVoiceLoop(pi, services, state, ctx);
+	});
+
+	pi.on("session_tree", async (_event, ctx) => {
+		reloadConfig(ctx.cwd || lastCwd);
+	});
+}

package/src/sarvam.ts

@@ -0,0 +1,311 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import { SarvamAIClient } from "sarvamai";
+import type { AudioRuntime } from "./audio.js";
+import type { PiListensConfig, SttMode } from "./config.js";
+
+export interface TranscriptionResult {
+	transcript: string;
+	languageCode?: string;
+	languageProbability?: number;
+	requestId?: string;
+}
+
+export interface SynthesisResult {
+	path: string;
+	bytes: number;
+}
+
+type StreamingData = {
+	transcript?: string;
+	request_id?: string;
+	language_code?: string;
+	language_probability?: number;
+	error?: string;
+	code?: string;
+	event_type?: string;
+	signal_type?: string;
+};
+
+type StreamingResponse = {
+	type?: "data" | "error" | "events" | string;
+	data?: StreamingData;
+};
+
+type StreamingSocket = {
+	transcribe(params: { audio: string; sample_rate: number; encoding: "audio/wav" }): void;
+	flush(): void;
+	close(): void;
+	waitForOpen(): Promise<void>;
+	onMessage(handler: (message: StreamingResponse) => void): void;
+	onError(handler: (error: Error) => void): void;
+};
+
+export class SarvamSpeechClient {
+	private client: SarvamAIClient | null = null;
+	private clientKey: string | null = null;
+
+	constructor(private readonly getConfig: () => PiListensConfig) {}
+
+	async transcribeMicrophone(audio: AudioRuntime, signal?: AbortSignal, options: { seconds?: number; mode?: SttMode } = {}): Promise<TranscriptionResult> {
+		const config = this.getConfig();
+		return this.withStreamingSocket(signal, options.mode, "pcm_s16le", async (socket, collect) => {
+			const recorderController = new AbortController();
+			const stopRecorder = () => recorderController.abort();
+			signal?.addEventListener("abort", stopRecorder, { once: true });
+			const startedAt = Date.now();
+			let speechStarted = false;
+			let lastVoiceAt = Date.now();
+			let pending = Buffer.alloc(0);
+			const chunkBytes = Math.max(1600, Math.round(config.recordSampleRate * 2 * (config.streamChunkMs / 1000)));
+			const maxSeconds = Math.max(1, Math.round(options.seconds ?? config.streamMaxSeconds ?? config.recordSeconds));
+
+			const streamSignal = combineSignals(signal, recorderController.signal);
+			try {
+				for await (const chunk of audio.streamPcm(streamSignal.signal)) {
+					if (signal?.aborted) throw new Error("Cancelled");
+					const now = Date.now();
+					const rms = pcm16Rms(chunk);
+					if (rms > silenceThresholdAmplitude(config.silenceThreshold)) {
+						speechStarted = true;
+						lastVoiceAt = now;
+					}
+
+					pending = Buffer.concat([pending, chunk]);
+					while (pending.byteLength >= chunkBytes) {
+						const audioChunk = pending.subarray(0, chunkBytes);
+						pending = pending.subarray(chunkBytes);
+						socket.transcribe({ audio: audioChunk.toString("base64"), sample_rate: config.recordSampleRate, encoding: "audio/wav" });
+					}
+
+					const hitMaxDuration = now - startedAt >= maxSeconds * 1000;
+					const hitTrailingSilence = speechStarted && now - lastVoiceAt >= config.silenceStopSeconds * 1000;
+					if (hitMaxDuration || hitTrailingSilence) break;
+				}
+				if (pending.byteLength > 0) {
+					socket.transcribe({ audio: pending.toString("base64"), sample_rate: config.recordSampleRate, encoding: "audio/wav" });
+				}
+				socket.flush();
+				await collect();
+			} finally {
+				streamSignal.cleanup();
+				recorderController.abort();
+				signal?.removeEventListener("abort", stopRecorder);
+			}
+		});
+	}
+
+	async transcribeFile(path: string, signal?: AbortSignal, options: { mode?: SttMode } = {}): Promise<TranscriptionResult> {
+		const config = this.getConfig();
+		const audio = await readFile(path);
+		return this.withStreamingSocket(signal, options.mode, "wav", async (socket, collect) => {
+			socket.transcribe({ audio: audio.toString("base64"), sample_rate: config.recordSampleRate, encoding: "audio/wav" });
+			socket.flush();
+			await collect();
+		});
+	}
+
+	async synthesizeToFile(text: string, path: string, signal?: AbortSignal): Promise<SynthesisResult> {
+		const config = this.getConfig();
+		const client = this.getClient(config);
+		const response = await client.textToSpeech.convertStream(
+			{
+				text,
+				target_language_code: config.ttsLanguageCode as never,
+				speaker: config.ttsSpeaker as never,
+				model: config.ttsModel as never,
+				pace: config.ttsPace,
+				temperature: config.ttsTemperature,
+				speech_sample_rate: config.ttsSampleRate as never,
+				enable_preprocessing: true,
+				output_audio_codec: config.ttsOutputCodec as never,
+			},
+			{ abortSignal: signal },
+		);
+		const arrayBuffer = await response.arrayBuffer();
+		const buffer = Buffer.from(arrayBuffer);
+		await writeFile(path, buffer);
+		return { path, bytes: buffer.byteLength };
+	}
+
+	private async withStreamingSocket(
+		signal: AbortSignal | undefined,
+		mode: SttMode | undefined,
+		inputAudioCodec: "wav" | "pcm_s16le",
+		streamAudio: (
+			socket: StreamingSocket,
+			collect: () => Promise<void>,
+		) => Promise<void>,
+	): Promise<TranscriptionResult> {
+		const config = this.getConfig();
+		this.getClient(config); // validate/cache API key for TTS; STT uses raw WebSocket so the documented `mode` query parameter is preserved.
+		let transcript = "";
+		let requestId: string | undefined;
+		let languageCode: string | undefined;
+		let languageProbability: number | undefined;
+		let streamError: Error | undefined;
+		let lastMessageAt = Date.now();
+
+		const socket = connectStreamingSocket(config, mode ?? (config.translateInputToEnglish ? "translate" : config.sttMode), inputAudioCodec);
+
+		const closeOnAbort = () => socket.close();
+		signal?.addEventListener("abort", closeOnAbort, { once: true });
+		socket.onMessage((message: StreamingResponse) => {
+			lastMessageAt = Date.now();
+			if (message.type === "error") {
+				streamError = new Error(message.data?.error ?? message.data?.code ?? "Sarvam streaming STT failed");
+				return;
+			}
+			if (message.type !== "data") return;
+			const data = message.data;
+			if (!data) return;
+			transcript = mergeTranscript(transcript, data.transcript ?? "");
+			requestId = data.request_id ?? requestId;
+			languageCode = data.language_code ?? languageCode;
+			languageProbability = data.language_probability ?? languageProbability;
+		});
+		socket.onError((error: Error) => { streamError = error; });
+
+		try {
+			await socket.waitForOpen();
+			await streamAudio(socket, async () => {
+				const startedWaitingAt = Date.now();
+				while (Date.now() - startedWaitingAt < 3000) {
+					if (streamError) throw streamError;
+					if (Date.now() - lastMessageAt > 850 && transcript.trim()) break;
+					await delay(100, undefined, { signal }).catch((err) => { throw err; });
+				}
+			});
+			if (streamError) throw streamError;
+			return { transcript: transcript.trim(), languageCode, languageProbability, requestId };
+		} finally {
+			signal?.removeEventListener("abort", closeOnAbort);
+			socket.close();
+		}
+	}
+
+	private getClient(config: PiListensConfig): SarvamAIClient {
+		if (!config.apiKey) {
+			throw new Error("Sarvam API key is not configured. Set SARVAM_API_KEY or run with a pi-listens config file.");
+		}
+		if (!this.client || this.clientKey !== config.apiKey) {
+			this.client = new SarvamAIClient({ apiSubscriptionKey: config.apiKey });
+			this.clientKey = config.apiKey;
+		}
+		return this.client;
+	}
+}
+
+function mergeTranscript(existing: string, incoming: string): string {
+	const previous = existing.trim();
+	const next = incoming.trim();
+	if (!next) return previous;
+	if (!previous) return next;
+	if (next === previous || previous.endsWith(next) || previous.includes(next)) return previous;
+	if (next.startsWith(previous)) return next;
+	return `${previous} ${next}`;
+}
+
+function pcm16Rms(buffer: Buffer): number {
+	let total = 0;
+	let count = 0;
+	for (let offset = 0; offset + 1 < buffer.byteLength; offset += 2) {
+		const sample = buffer.readInt16LE(offset);
+		total += sample * sample;
+		count++;
+	}
+	return count ? Math.sqrt(total / count) : 0;
+}
+
+function silenceThresholdAmplitude(threshold: string): number {
+	const trimmed = threshold.trim();
+	if (trimmed.endsWith("%")) {
+		const percent = Number.parseFloat(trimmed.slice(0, -1));
+		if (Number.isFinite(percent)) return 32767 * (percent / 100);
+	}
+	const numeric = Number.parseFloat(trimmed);
+	return Number.isFinite(numeric) ? numeric : 327;
+}
+
+function connectStreamingSocket(config: PiListensConfig, mode: SttMode, inputAudioCodec: "wav" | "pcm_s16le"): StreamingSocket {
+	if (!config.apiKey) {
+		throw new Error("Sarvam API key is not configured. Set SARVAM_API_KEY or run with a pi-listens config file.");
+	}
+	const url = new URL("wss://api.sarvam.ai/speech-to-text/ws");
+	url.searchParams.set("language-code", config.sttLanguageCode);
+	url.searchParams.set("model", config.sttModel);
+	url.searchParams.set("mode", mode);
+	url.searchParams.set("input_audio_codec", inputAudioCodec);
+	url.searchParams.set("sample_rate", String(config.recordSampleRate));
+	url.searchParams.set("high_vad_sensitivity", "true");
+	url.searchParams.set("vad_signals", "true");
+	url.searchParams.set("flush_signal", "true");
+
+	const ws = new WebSocket(url, [`api-subscription-key.${config.apiKey}`]);
+	const messageHandlers = new Set<(message: StreamingResponse) => void>();
+	const errorHandlers = new Set<(error: Error) => void>();
+	ws.addEventListener("message", (event) => {
+		try {
+			const parsed = JSON.parse(String(event.data)) as StreamingResponse;
+			for (const handler of messageHandlers) handler(parsed);
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			for (const handler of errorHandlers) handler(error);
+		}
+	});
+	ws.addEventListener("error", () => {
+		for (const handler of errorHandlers) handler(new Error("Sarvam streaming WebSocket error"));
+	});
+
+	return {
+		transcribe(params) {
+			ws.send(JSON.stringify({ audio: { data: params.audio, sample_rate: params.sample_rate, encoding: params.encoding } }));
+		},
+		flush() {
+			ws.send(JSON.stringify({ type: "flush" }));
+		},
+		close() {
+			if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) ws.close();
+		},
+		waitForOpen() {
+			if (ws.readyState === WebSocket.OPEN) return Promise.resolve();
+			return new Promise<void>((resolve, reject) => {
+				const cleanup = () => {
+					ws.removeEventListener("open", onOpen);
+					ws.removeEventListener("error", onError);
+					ws.removeEventListener("close", onClose);
+				};
+				const onOpen = () => { cleanup(); resolve(); };
+				const onError = () => { cleanup(); reject(new Error("Sarvam streaming WebSocket failed to open")); };
+				const onClose = () => { cleanup(); reject(new Error("Sarvam streaming WebSocket closed before opening")); };
+				ws.addEventListener("open", onOpen, { once: true });
+				ws.addEventListener("error", onError, { once: true });
+				ws.addEventListener("close", onClose, { once: true });
+			});
+		},
+		onMessage(handler) { messageHandlers.add(handler); },
+		onError(handler) { errorHandlers.add(handler); },
+	};
+}
+
+type CombinedSignal = { signal?: AbortSignal; cleanup: () => void };
+
+function combineSignals(...signals: Array<AbortSignal | undefined>): CombinedSignal {
+	const active = signals.filter((signal): signal is AbortSignal => Boolean(signal));
+	if (active.length === 0) return { signal: undefined, cleanup: () => undefined };
+	if (active.length === 1) return { signal: active[0], cleanup: () => undefined };
+	const controller = new AbortController();
+	const attached: AbortSignal[] = [];
+	const abort = () => controller.abort();
+	for (const signal of active) {
+		if (signal.aborted) { controller.abort(); break; }
+		signal.addEventListener("abort", abort, { once: true });
+		attached.push(signal);
+	}
+	return {
+		signal: controller.signal,
+		cleanup: () => {
+			for (const signal of attached) signal.removeEventListener("abort", abort);
+		},
+	};
+}

package/src/text.ts

@@ -0,0 +1,33 @@
+export function firstTextContent(message: unknown): string {
+	if (!message || typeof message !== "object") return "";
+	const content = (message as { content?: unknown }).content;
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((part) => {
+			if (!part || typeof part !== "object") return "";
+			const p = part as { type?: string; text?: string };
+			return p.type === "text" && typeof p.text === "string" ? p.text : "";
+		})
+		.filter(Boolean)
+		.join("\n")
+		.trim();
+}
+
+export function prepareSpokenText(text: string, maxChars: number): string {
+	let prepared = text
+		.replace(/```[\s\S]*?```/g, " I am skipping a code block. ")
+		.replace(/`([^`]+)`/g, "$1")
+		.replace(/https?:\/\/\S+/g, "link")
+		.replace(/\s+/g, " ")
+		.trim();
+	if (prepared.length > maxChars) {
+		prepared = `${prepared.slice(0, Math.max(0, maxChars - 80)).trim()}… I have more details on screen.`;
+	}
+	return prepared;
+}
+
+export function conciseTranscript(transcript: string): string {
+	const trimmed = transcript.trim();
+	return trimmed.length === 0 ? "(no speech recognized)" : trimmed;
+}