feat(tool-youtube-transcript): YouTube transcription tool

New standard tool extension backed by a self-hosted transcriber service
(http://100.102.55.49:41090, Tailscale, no API key). One tool
youtube_transcript — fetches transcripts for YouTube videos. Returns
completed (full text + timestamped segments), queued/processing (position
+ ETA + .youtube_subtitles_pending retry convention), or failed (error).

Pure core: validateUrl + format* functions + truncateOutput. Injected
edge: TranscriptClient (injectable fetchFn, AbortSignal.any for
cancellation). concurrencySafe true, capabilities network. 30 tests.

Verified: tsc EXIT 0, 1152 vitest, biome clean (327 files). Boot smoke
clean.

1 files changed, 114 insertions, 0 deletions

diff --git a/packages/tool-youtube-transcript/src/tool.test.ts b/packages/tool-youtube-transcript/src/tool.test.ts
new file mode 100644
index 0000000..adf95ed
--- /dev/null
+++ b/packages/tool-youtube-transcript/src/tool.test.ts
@@ -0,0 +1,114 @@
+import { createLogger, type LogRecord, type ToolExecuteContext } from "@dispatch/kernel";
+import { describe, expect, it } from "vitest";
+import type { TranscriptClient } from "./client.js";
+import type { TranscriptResponse } from "./format.js";
+import { createYoutubeTranscriptTool } from "./tool.js";
+
+function stubCtx(overrides?: Partial<ToolExecuteContext>): ToolExecuteContext {
+	return {
+		toolCallId: "test-call-1",
+		onOutput: () => {},
+		signal: new AbortController().signal,
+		log: createLogger(
+			{ extensionId: "test" },
+			{ emit: () => {} },
+			{ now: () => 0, newId: () => "id" },
+		),
+		...overrides,
+	};
+}
+
+function makeStubClient(
+	responder: (url: string, signal: AbortSignal) => Promise<TranscriptResponse>,
+): TranscriptClient {
+	return { getTranscript: (url, signal) => responder(url, signal) };
+}
+
+describe("youtube_transcript", () => {
+	it("returns formatted transcript on completed", async () => {
+		const client = makeStubClient(async () => ({
+			status: "completed",
+			video_id: "vid1",
+			full_text: "Hello world.",
+			segments: [{ text: "Hello world.", start: 0, duration: 2 }],
+		}));
+		const tool = createYoutubeTranscriptTool({ client });
+		const result = await tool.execute({ url: "https://youtu.be/vid1" }, stubCtx());
+		expect(result.isError).toBe(undefined);
+		expect(result.content).toContain("## Transcript for https://youtu.be/vid1");
+		expect(result.content).toContain("**Video ID:** vid1");
+		expect(result.content).toContain("Hello world.");
+		expect(result.content).toContain("[0:00] Hello world.");
+	});
+
+	it("returns queued message with pending file instruction", async () => {
+		const client = makeStubClient(async () => ({
+			status: "queued",
+			video_id: "vid2",
+			position: 1,
+			estimated_seconds: 30,
+		}));
+		const tool = createYoutubeTranscriptTool({ client });
+		const result = await tool.execute({ url: "https://youtu.be/vid2" }, stubCtx());
+		expect(result.isError).toBe(undefined);
+		expect(result.content).toContain("status: queued");
+		expect(result.content).toContain("queue position: 1");
+		expect(result.content).toContain("in ~30s");
+		expect(result.content).toContain(".youtube_subtitles_pending");
+		expect(result.content).toContain("https://youtu.be/vid2");
+	});
+
+	it("returns failed message", async () => {
+		const client = makeStubClient(async () => ({
+			status: "failed",
+			video_id: "vid3",
+			error: "Video unavailable",
+			error_type: "NotFoundError",
+		}));
+		const tool = createYoutubeTranscriptTool({ client });
+		const result = await tool.execute({ url: "https://youtu.be/vid3" }, stubCtx());
+		expect(result.isError).toBe(undefined);
+		expect(result.content).toContain("Error type: NotFoundError");
+		expect(result.content).toContain("Details: Video unavailable");
+	});
+
+	it("validation error returns isError", async () => {
+		const client = makeStubClient(async () => {
+			throw new Error("should not be called");
+		});
+		const tool = createYoutubeTranscriptTool({ client });
+		const result = await tool.execute({ url: "" }, stubCtx());
+		expect(result.isError).toBe(true);
+		expect(result.content).toContain("url");
+	});
+
+	it("uses conversationId from ctx (not required but passed through)", async () => {
+		const records: LogRecord[] = [];
+		const client = makeStubClient(async () => ({
+			status: "completed",
+			video_id: "vid4",
+			full_text: "text",
+			segments: [],
+		}));
+		const tool = createYoutubeTranscriptTool({ client });
+		const ctx = stubCtx({
+			conversationId: "conv-xyz",
+			log: createLogger(
+				{ extensionId: "test", conversationId: "conv-xyz" },
+				{
+					emit: (r) => {
+						records.push(r);
+					},
+				},
+				{ now: () => 0, newId: () => "id" },
+			),
+		});
+		const result = await tool.execute({ url: "https://youtu.be/vid4" }, ctx);
+		expect(result.isError).toBe(undefined);
+		expect(result.content).toContain("## Transcript for");
+		// The execute span flows through ctx.log, which carries conversationId.
+		const spanOpen = records.find((r) => r.kind === "span-open");
+		expect(spanOpen).toBeDefined();
+		expect(spanOpen?.conversationId).toBe("conv-xyz");
+	});
+});