@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.3-beta.2

package/src/routes/local-inference-tts-route.d.ts

@@ -0,0 +1,7 @@
+import type http from "node:http";
+import { type CompatRuntimeState } from "./compat-helpers";
+export declare function sanitizeLocalInferenceSpeechText(input: string): string;
+export declare function normalizeAudioBytes(value: unknown): Uint8Array;
+export declare function sniffAudioContentType(bytes: Uint8Array): string;
+export declare function handleLocalInferenceTtsRoute(req: http.IncomingMessage, res: http.ServerResponse, state: CompatRuntimeState): Promise<boolean>;
+//# sourceMappingURL=local-inference-tts-route.d.ts.map

package/src/routes/local-inference-tts-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-inference-tts-route.d.ts","sourceRoot":"","sources":["local-inference-tts-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EACN,KAAK,kBAAkB,EAIvB,MAAM,kBAAkB,CAAC;AAS1B,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAatE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAW9D;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CA0B/D;AA0DD,wBAAsB,4BAA4B,CACjD,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,EACxB,KAAK,EAAE,kBAAkB,GACvB,OAAO,CAAC,OAAO,CAAC,CAiGlB"}

package/src/routes/local-inference-tts-route.test.ts

@@ -0,0 +1,179 @@
+import * as http from "node:http";
+import { Socket } from "node:net";
+import { describe, expect, it, vi } from "vitest";
+import type { CompatRuntimeState } from "./compat-helpers";
+import {
+	handleLocalInferenceTtsRoute,
+	sanitizeLocalInferenceSpeechText,
+} from "./local-inference-tts-route";
+
+function wavBytes(): Uint8Array {
+	return new Uint8Array([
+		0x52, 0x49, 0x46, 0x46, 0x24, 0x00, 0x00, 0x00, 0x57, 0x41, 0x56, 0x45,
+		0x66, 0x6d, 0x74, 0x20,
+	]);
+}
+
+function fakeReq(body?: unknown): http.IncomingMessage {
+	const req = new http.IncomingMessage(new Socket());
+	req.method = "POST";
+	req.url = "/api/tts/local-inference";
+	req.headers = { host: "localhost:2138" };
+	Object.defineProperty(req.socket, "remoteAddress", {
+		value: "127.0.0.1",
+		configurable: true,
+	});
+	if (body !== undefined) {
+		(req as { body?: unknown }).body = body;
+	}
+	return req;
+}
+
+function fakeRes(): {
+	res: http.ServerResponse;
+	bodyBuffer: () => Buffer;
+	status: () => number;
+	header: (name: string) => string | undefined;
+} {
+	const req = new http.IncomingMessage(new Socket());
+	const res = new http.ServerResponse(req);
+	let body = Buffer.alloc(0);
+	let status = 200;
+	const headers = new Map<string, string>();
+	res.setHeader = ((
+		name: string,
+		value: number | string | readonly string[],
+	) => {
+		headers.set(String(name).toLowerCase(), String(value));
+		return res;
+	}) as typeof res.setHeader;
+	res.writeHead = ((code: number, values?: http.OutgoingHttpHeaders) => {
+		status = code;
+		res.statusCode = code;
+		if (values) {
+			for (const [key, value] of Object.entries(values)) {
+				headers.set(key.toLowerCase(), String(value));
+			}
+		}
+		return res;
+	}) as typeof res.writeHead;
+	res.end = ((chunk?: string | Uint8Array | Buffer) => {
+		if (typeof chunk === "string") {
+			body = Buffer.concat([body, Buffer.from(chunk)]);
+		} else if (chunk) {
+			body = Buffer.concat([body, Buffer.from(chunk)]);
+		}
+		return res;
+	}) as typeof res.end;
+	return {
+		res,
+		bodyBuffer: () => body,
+		status: () => status,
+		header: (name) => headers.get(name.toLowerCase()),
+	};
+}
+
+describe("local inference TTS route", () => {
+	it("sanitizes assistant markup before synthesis", () => {
+		expect(
+			sanitizeLocalInferenceSpeechText(
+				"<think>hidden</think>Hello `there` [friend](https://example.com) https://example.com",
+			),
+		).toBe("Hello there friend");
+	});
+
+	it("falls through missing providers and returns WAV bytes", async () => {
+		const useModel = vi
+			.fn()
+			.mockRejectedValueOnce(
+				new Error("No handler found for delegate type: TEXT_TO_SPEECH"),
+			)
+			.mockResolvedValueOnce(wavBytes());
+		const state: CompatRuntimeState = {
+			current: { useModel } as unknown as CompatRuntimeState["current"],
+		};
+		const out = fakeRes();
+
+		const handled = await handleLocalInferenceTtsRoute(
+			fakeReq({ text: "Hello" }),
+			out.res,
+			state,
+		);
+
+		const secondParams = useModel.mock.calls[1]?.[1] as
+			| { text?: string; signal?: AbortSignal; voice?: string }
+			| undefined;
+		expect(handled).toBe(true);
+		expect(useModel).toHaveBeenCalledTimes(2);
+		expect(useModel.mock.calls[1]?.[2]).toBe("capacitor-llama");
+		expect(secondParams).toMatchObject({ text: "Hello" });
+		expect(secondParams?.signal).toBeInstanceOf(AbortSignal);
+		expect(out.status()).toBe(200);
+		expect(out.header("content-type")).toBe("audio/wav");
+		expect(out.bodyBuffer()).toEqual(Buffer.from(wavBytes()));
+	});
+
+	it("forwards voice, model, speed, sample rate, and format hints", async () => {
+		const useModel = vi.fn().mockResolvedValue(wavBytes());
+		const state: CompatRuntimeState = {
+			current: { useModel } as unknown as CompatRuntimeState["current"],
+		};
+		const out = fakeRes();
+
+		await handleLocalInferenceTtsRoute(
+			fakeReq({
+				text: "Hello",
+				voiceId: "narrator",
+				modelId: "omnivoice-q4",
+				speed: 1.15,
+				sampleRate: 24_000,
+				format: "wav",
+			}),
+			out.res,
+			state,
+		);
+
+		expect(useModel.mock.calls[0]?.[1]).toMatchObject({
+			text: "Hello",
+			voice: "narrator",
+			modelId: "omnivoice-q4",
+			speed: 1.15,
+			sampleRate: 24_000,
+			format: "wav",
+		});
+	});
+
+	it("aborts TTS on client close without writing a synthetic 502", async () => {
+		let aborted = false;
+		let signalReady!: (signal: AbortSignal | undefined) => void;
+		const signalReceived = new Promise<AbortSignal | undefined>((resolve) => {
+			signalReady = resolve;
+		});
+		const useModel = vi.fn((_type, params: { signal?: AbortSignal }) => {
+			signalReady(params.signal);
+			return new Promise<Uint8Array>((_resolve, reject) => {
+				params.signal?.addEventListener(
+					"abort",
+					() => {
+						aborted = true;
+						reject(new Error("aborted"));
+					},
+					{ once: true },
+				);
+			});
+		});
+		const state: CompatRuntimeState = {
+			current: { useModel } as unknown as CompatRuntimeState["current"],
+		};
+		const req = fakeReq({ text: "Hello" });
+		const out = fakeRes();
+
+		const handledPromise = handleLocalInferenceTtsRoute(req, out.res, state);
+		await expect(signalReceived).resolves.toBeInstanceOf(AbortSignal);
+		req.emit("close");
+		await expect(handledPromise).resolves.toBe(true);
+
+		expect(aborted).toBe(true);
+		expect(out.bodyBuffer().length).toBe(0);
+	});
+});

package/src/routes/local-inference-tts-route.ts

@@ -0,0 +1,230 @@
+import type http from "node:http";
+import { type AgentRuntime, ModelType } from "@elizaos/core";
+import {
+	type CompatRuntimeState,
+	ensureRouteAuthorized,
+	readCompatJsonBody,
+	sendJson,
+} from "./compat-helpers";
+
+const LOCAL_TTS_PROVIDER_IDS = [
+	"eliza-local-inference",
+	"capacitor-llama",
+	"eliza-device-bridge",
+	"eliza-aosp-llama",
+] as const;
+
+export function sanitizeLocalInferenceSpeechText(input: string): string {
+	let text = input.normalize("NFKC");
+	text = text.replace(/<think\b[^>]*>[\s\S]*?(?:<\/think>|$)/gi, " ");
+	text = text.replace(
+		/<(analysis|reasoning|tool_calls?|tools?)\b[^>]*>[\s\S]*?(?:<\/\1>|$)/gi,
+		" ",
+	);
+	text = text.replace(/```[\s\S]*?```/g, " ");
+	text = text.replace(/`([^`]+)`/g, "$1");
+	text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1");
+	text = text.replace(/<[^>\n]+>/g, " ");
+	text = text.replace(/\bhttps?:\/\/\S+/gi, " ");
+	return text.replace(/\s+/g, " ").trim();
+}
+
+export function normalizeAudioBytes(value: unknown): Uint8Array {
+	if (value instanceof Uint8Array) {
+		return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+	}
+	if (value instanceof ArrayBuffer) {
+		return new Uint8Array(value);
+	}
+	if (ArrayBuffer.isView(value)) {
+		return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+	}
+	throw new Error("TEXT_TO_SPEECH returned a non-binary payload");
+}
+
+export function sniffAudioContentType(bytes: Uint8Array): string {
+	if (
+		bytes.length >= 12 &&
+		bytes[0] === 0x52 &&
+		bytes[1] === 0x49 &&
+		bytes[2] === 0x46 &&
+		bytes[3] === 0x46 &&
+		bytes[8] === 0x57 &&
+		bytes[9] === 0x41 &&
+		bytes[10] === 0x56 &&
+		bytes[11] === 0x45
+	) {
+		return "audio/wav";
+	}
+	if (
+		bytes.length >= 3 &&
+		bytes[0] === 0x49 &&
+		bytes[1] === 0x44 &&
+		bytes[2] === 0x33
+	) {
+		return "audio/mpeg";
+	}
+	if (bytes.length >= 2 && bytes[0] === 0xff && (bytes[1] & 0xe0) === 0xe0) {
+		return "audio/mpeg";
+	}
+	return "application/octet-stream";
+}
+
+function isMissingTtsProviderError(error: unknown): boolean {
+	return (
+		error instanceof Error &&
+		/No handler found for delegate type: TEXT_TO_SPEECH/.test(error.message)
+	);
+}
+
+interface LocalInferenceTtsRequest {
+	text: string;
+	voice?: string;
+	model?: string;
+	modelId?: string;
+	speed?: number;
+	sampleRate?: number;
+	format?: string;
+	signal?: AbortSignal;
+}
+
+function optionalString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function optionalPositiveNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value > 0
+		? value
+		: undefined;
+}
+
+async function useLocalInferenceTts(
+	runtime: AgentRuntime,
+	request: LocalInferenceTtsRequest,
+	signal?: AbortSignal,
+): Promise<Uint8Array> {
+	let lastError: unknown;
+	for (const provider of LOCAL_TTS_PROVIDER_IDS) {
+		try {
+			return normalizeAudioBytes(
+				await runtime.useModel(
+					ModelType.TEXT_TO_SPEECH,
+					{ ...request, ...(signal ? { signal } : {}) },
+					provider,
+				),
+			);
+		} catch (err) {
+			lastError = err;
+			if (!isMissingTtsProviderError(err)) throw err;
+		}
+	}
+	if (lastError instanceof Error) throw lastError;
+	throw new Error("No local-inference TEXT_TO_SPEECH provider is registered");
+}
+
+function isClosed(res: http.ServerResponse): boolean {
+	return res.destroyed || res.writableEnded;
+}
+
+export async function handleLocalInferenceTtsRoute(
+	req: http.IncomingMessage,
+	res: http.ServerResponse,
+	state: CompatRuntimeState,
+): Promise<boolean> {
+	const method = req.method?.toUpperCase() ?? "GET";
+	const url = new URL(req.url ?? "/", "http://localhost");
+	if (method !== "POST" || url.pathname !== "/api/tts/local-inference") {
+		return false;
+	}
+
+	if (!(await ensureRouteAuthorized(req, res, state))) return true;
+
+	const body = await readCompatJsonBody(req, res);
+	if (!body || typeof body !== "object") return true;
+
+	const rawText = body.text;
+	const text =
+		typeof rawText === "string"
+			? sanitizeLocalInferenceSpeechText(rawText)
+			: "";
+	if (!text) {
+		sendJson(res, 400, { error: "Missing text" });
+		return true;
+	}
+
+	const ttsRequest: LocalInferenceTtsRequest = {
+		text,
+		...(optionalString(body.voice)
+			? { voice: optionalString(body.voice) }
+			: {}),
+		...(optionalString(body.voiceId)
+			? { voice: optionalString(body.voiceId) }
+			: {}),
+		...(optionalString(body.model)
+			? { model: optionalString(body.model) }
+			: {}),
+		...(optionalString(body.modelId)
+			? { modelId: optionalString(body.modelId) }
+			: {}),
+		...(optionalPositiveNumber(body.speed)
+			? { speed: optionalPositiveNumber(body.speed) }
+			: {}),
+		...(optionalPositiveNumber(body.sampleRate)
+			? { sampleRate: optionalPositiveNumber(body.sampleRate) }
+			: {}),
+		...(optionalString(body.format)
+			? { format: optionalString(body.format) }
+			: {}),
+	};
+
+	const runtime = state.current;
+	if (!runtime) {
+		sendJson(res, 503, {
+			error: "Local inference TEXT_TO_SPEECH is not available",
+		});
+		return true;
+	}
+
+	const abortController = new AbortController();
+	let completed = false;
+	let clientClosed = false;
+	const abortOnClose = () => {
+		clientClosed = true;
+		if (!completed && !abortController.signal.aborted) {
+			abortController.abort();
+		}
+	};
+	req.on("close", abortOnClose);
+	res.on("close", abortOnClose);
+	try {
+		const bytes = await useLocalInferenceTts(
+			runtime,
+			ttsRequest,
+			abortController.signal,
+		);
+		if (bytes.length === 0) {
+			sendJson(res, 502, {
+				error: "Local inference TEXT_TO_SPEECH returned empty audio",
+			});
+			return true;
+		}
+		completed = true;
+		res.writeHead(200, {
+			"Content-Type": sniffAudioContentType(bytes),
+			"Cache-Control": "no-store",
+			"Content-Length": String(bytes.byteLength),
+		});
+		res.end(Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength));
+	} catch (err) {
+		if (!clientClosed && !abortController.signal.aborted && !isClosed(res)) {
+			sendJson(res, 502, {
+				error: `Local inference TTS error: ${err instanceof Error ? err.message : String(err)}`,
+			});
+		}
+	} finally {
+		completed = true;
+		req.off("close", abortOnClose);
+		res.off("close", abortOnClose);
+	}
+	return true;
+}

package/src/routes/transcript-audio-store.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Transcript audio persistence (#8789).
+ *
+ * The transcript create route runs in plugin-local-inference, which cannot
+ * import the agent-internal media store (`packages/agent/src/api/media-store.ts`
+ * is not exported). But that store is just a content-addressed write under
+ * `<stateDir>/media/<sha256>.<ext>`, served by the agent's `serveMediaFile` at
+ * `/api/media/<sha256>.<ext>` (with HTTP Range, so `<audio>` scrubbing works).
+ * Writing the session WAV the same way — via core's `resolveStateDir` — lands it
+ * in the exact dir the agent already serves, so transcript audio plays back
+ * with zero extra wiring. Idempotent (sha256 filename).
+ */
+/** Persist mono PCM16 WAV bytes; returns the served `/api/media/<hash>.wav` URL. */
+export declare function persistTranscriptAudioWav(wav: Buffer): string;
+//# sourceMappingURL=transcript-audio-store.d.ts.map

package/src/routes/transcript-audio-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript-audio-store.d.ts","sourceRoot":"","sources":["transcript-audio-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,oFAAoF;AACpF,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO7D"}

package/src/routes/transcript-audio-store.ts

@@ -0,0 +1,27 @@
+/**
+ * Transcript audio persistence (#8789).
+ *
+ * The transcript create route runs in plugin-local-inference, which cannot
+ * import the agent-internal media store (`packages/agent/src/api/media-store.ts`
+ * is not exported). But that store is just a content-addressed write under
+ * `<stateDir>/media/<sha256>.<ext>`, served by the agent's `serveMediaFile` at
+ * `/api/media/<sha256>.<ext>` (with HTTP Range, so `<audio>` scrubbing works).
+ * Writing the session WAV the same way — via core's `resolveStateDir` — lands it
+ * in the exact dir the agent already serves, so transcript audio plays back
+ * with zero extra wiring. Idempotent (sha256 filename).
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveStateDir } from "@elizaos/core";
+
+/** Persist mono PCM16 WAV bytes; returns the served `/api/media/<hash>.wav` URL. */
+export function persistTranscriptAudioWav(wav: Buffer): string {
+	const hash = createHash("sha256").update(wav).digest("hex");
+	const dir = join(resolveStateDir(), "media");
+	mkdirSync(dir, { recursive: true });
+	const file = join(dir, `${hash}.wav`);
+	if (!existsSync(file)) writeFileSync(file, wav);
+	return `/api/media/${hash}.wav`;
+}

package/src/routes/transcripts-routes.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Transcript HTTP routes (#8789) — `/api/transcripts*`, served as rawPath plugin
+ * routes (on `runtime.routes`, dispatched by both the upstream agent server and
+ * app-core) so the Transcripts view + the recording pipeline have a backend.
+ * Audio is served by the existing content-addressed media store via each
+ * record's `audioUrl`, so no separate audio route is needed.
+ *
+ * Private routes: the host dispatcher answers 401 for unauthenticated callers.
+ */
+import type { Route, UUID } from "@elizaos/core";
+import { type Transcript, type TranscriptScope, type TranscriptSegment, type TranscriptSource } from "@elizaos/shared/transcripts";
+/** The body a recording session POSTs to create a transcript record. */
+export interface CreateTranscriptRequest {
+    /** Optional — the route derives these from the agent context when absent (the
+     *  shell client doesn't carry world/room/entity ids). */
+    worldId?: UUID;
+    roomId?: UUID;
+    entityId?: UUID;
+    title?: string;
+    source?: TranscriptSource;
+    scope?: TranscriptScope;
+    segments: TranscriptSegment[];
+    audioUrl?: string;
+    audioContentType?: string;
+    /** Base64 WAV bytes — persisted to the media store; sets audioUrl. */
+    audioBase64?: string;
+    createdAt?: number;
+}
+/**
+ * Build a full {@link Transcript} from a create request — derives duration +
+ * speaker count from the segments, defaults title/scope/status. Pure (id + now
+ * injected) so it is unit-testable.
+ */
+export declare function buildTranscriptFromRequest(body: CreateTranscriptRequest, id: string, now: number): Transcript;
+export declare const transcriptsRoutes: Route[];
+//# sourceMappingURL=transcripts-routes.d.ts.map

package/src/routes/transcripts-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcripts-routes.d.ts","sourceRoot":"","sources":["transcripts-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACX,KAAK,EAGL,IAAI,EACJ,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EAGrB,MAAM,6BAA6B,CAAC;AAarC,wEAAwE;AACxE,MAAM,WAAW,uBAAuB;IACvC;6DACyD;IACzD,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACzC,IAAI,EAAE,uBAAuB,EAC7B,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,MAAM,GACT,UAAU,CAiBZ;AAyED,eAAO,MAAM,iBAAiB,EAAE,KAAK,EAKpC,CAAC"}

package/src/routes/transcripts-routes.test.ts

@@ -0,0 +1,144 @@
+import type { Memory, RouteHandlerContext, UUID } from "@elizaos/core";
+import type { TranscriptSegment } from "@elizaos/shared/transcripts";
+import { describe, expect, it } from "vitest";
+import {
+	buildTranscriptFromRequest,
+	type CreateTranscriptRequest,
+	transcriptsRoutes,
+} from "./transcripts-routes";
+
+const WORLD = "00000000-0000-0000-0000-0000000000ww" as UUID;
+const ROOM = "11111111-1111-1111-1111-111111111111" as UUID;
+const ENTITY = "22222222-2222-2222-2222-222222222222" as UUID;
+
+const segments: TranscriptSegment[] = [
+	{
+		id: "s1",
+		speakerLabel: "Alice",
+		startMs: 0,
+		endMs: 1000,
+		text: "hi there",
+		words: [],
+	},
+	{
+		id: "s2",
+		speakerLabel: "Bob",
+		startMs: 1200,
+		endMs: 2500,
+		text: "hello",
+		words: [],
+	},
+];
+
+function fakeRuntime(): { rows: Map<string, Memory>; runtime: unknown } {
+	const rows = new Map<string, Memory>();
+	const runtime = {
+		agentId: "agent-1" as UUID,
+		createMemory: async (m: Memory) => {
+			rows.set(m.id as string, m);
+			return m.id as UUID;
+		},
+		getMemories: async () => [...rows.values()],
+		getMemoryById: async (id: UUID) => rows.get(id) ?? null,
+		deleteMemory: async (id: UUID) => {
+			rows.delete(id);
+		},
+		getService: () => null, // no documents service in this test
+	};
+	return { rows, runtime };
+}
+
+function ctx(over: Partial<RouteHandlerContext>): RouteHandlerContext {
+	return {
+		params: {},
+		query: {},
+		body: undefined,
+		headers: {},
+		method: "GET",
+		path: "/api/transcripts",
+		inProcess: true,
+		...over,
+	} as RouteHandlerContext;
+}
+
+function handlerFor(type: string, path: string) {
+	const r = transcriptsRoutes.find((x) => x.type === type && x.path === path);
+	if (!r?.routeHandler) throw new Error(`no route ${type} ${path}`);
+	return r.routeHandler;
+}
+
+describe("buildTranscriptFromRequest", () => {
+	it("derives duration + speaker count + defaults", () => {
+		const body: CreateTranscriptRequest = {
+			worldId: WORLD,
+			roomId: ROOM,
+			entityId: ENTITY,
+			segments,
+			createdAt: 1000,
+		};
+		const t = buildTranscriptFromRequest(body, "id-1", 9000);
+		expect(t.durationMs).toBe(2500);
+		expect(t.speakerCount).toBe(2);
+		expect(t.scope).toBe("owner-private");
+		expect(t.source).toBe("voice-session");
+		expect(t.status).toBe("ready");
+		expect(t.createdAt).toBe(1000);
+		expect(t.endedAt).toBe(9000);
+		expect(t.title).toContain("Recording");
+	});
+});
+
+describe("transcripts routes", () => {
+	it("POST creates, GET reads it back, GET list summarizes, DELETE removes", async () => {
+		const { runtime } = fakeRuntime();
+		// No world/room/entity ids — the route derives them from the agent context.
+		const body: CreateTranscriptRequest = {
+			title: "Standup",
+			segments,
+		};
+		const created = await handlerFor(
+			"POST",
+			"/api/transcripts",
+		)(ctx({ runtime: runtime as never, body }));
+		expect(created.status).toBe(201);
+		const id = (created.body as { transcript: { id: string } }).transcript.id;
+		expect(typeof id).toBe("string");
+
+		const got = await handlerFor(
+			"GET",
+			"/api/transcripts/:id",
+		)(ctx({ runtime: runtime as never, params: { id } }));
+		expect(got.status).toBe(200);
+		expect(
+			(got.body as { transcript: { title: string } }).transcript.title,
+		).toBe("Standup");
+
+		const list = await handlerFor(
+			"GET",
+			"/api/transcripts",
+		)(ctx({ runtime: runtime as never }));
+		expect((list.body as { transcripts: unknown[] }).transcripts).toHaveLength(
+			1,
+		);
+
+		const del = await handlerFor(
+			"DELETE",
+			"/api/transcripts/:id",
+		)(ctx({ runtime: runtime as never, params: { id } }));
+		expect(del.status).toBe(200);
+		const after = await handlerFor(
+			"GET",
+			"/api/transcripts/:id",
+		)(ctx({ runtime: runtime as never, params: { id } }));
+		expect(after.status).toBe(404);
+	});
+
+	it("POST rejects a body with no segments", async () => {
+		const { runtime } = fakeRuntime();
+		const res = await handlerFor(
+			"POST",
+			"/api/transcripts",
+		)(ctx({ runtime: runtime as never, body: { segments: [] } }));
+		expect(res.status).toBe(400);
+	});
+});