@selesai/code 0.13.3 → 0.13.5

package/dist/extensions/pi-web-agent/src/presentation/fetch-presentation.ts

@@ -1,54 +1,54 @@
-import type { WebFetchHeadlessResponse, WebFetchResponse } from '../types.js';
-import type { PresentationEnvelope } from './types.js';
-
-type FetchLike = WebFetchResponse | WebFetchHeadlessResponse;
-
-function countWords(text: string | undefined): number | undefined {
-  return text?.trim() ? text.trim().split(/\s+/).length : undefined;
-}
-
-function firstExcerpt(text: string | undefined, maxChars = 240): string | undefined {
-  if (!text) {
-    return undefined;
-  }
-
-  return text.length <= maxChars ? text : `${text.slice(0, maxChars).trimEnd()}…`;
-}
-
-export function buildFetchPresentation(result: FetchLike): PresentationEnvelope {
-  const wordCount = countWords(result.content?.text);
-  const fallbackPrefix = result.metadata.fallbackFrom
-    ? `${result.metadata.fallbackFrom} failed; used ${result.metadata.method} fallback. `
-    : '';
-  const compact =
-    result.status === 'ok'
-      ? `${fallbackPrefix}Fetched page · article extracted${wordCount ? ` · ${wordCount} words` : ''}`
-      : result.status === 'needs_headless'
-        ? `${fallbackPrefix}Needs headless rendering: ${result.error?.message ?? 'Headless rendering recommended.'}`
-        : `${fallbackPrefix}Fetch failed: ${result.error?.message ?? 'Unknown fetch failure.'}`;
-
-  return {
-    mode: 'compact',
-    views: {
-      compact,
-      preview: result.content?.title
-        ? `${result.content.title}\n${firstExcerpt(result.content.text) ?? ''}`.trim()
-        : firstExcerpt(result.content?.text),
-      verbose:
-        result.status === 'ok'
-          ? [
-              `URL: ${result.url}`,
-              result.content?.title ? `Title: ${result.content.title}` : undefined,
-              firstExcerpt(result.content?.text, 500)
-            ]
-              .filter(Boolean)
-              .join('\n')
-          : undefined
-    },
-    metrics: {
-      wordCount,
-      cacheHit: result.metadata.cacheHit
-    },
-    sources: [{ title: result.content?.title ?? result.url, url: result.url }]
-  };
-}
+import type { WebFetchHeadlessResponse, WebFetchResponse } from '../types.js';
+import type { PresentationEnvelope } from './types.js';
+
+type FetchLike = WebFetchResponse | WebFetchHeadlessResponse;
+
+function countWords(text: string | undefined): number | undefined {
+  return text?.trim() ? text.trim().split(/\s+/).length : undefined;
+}
+
+function firstExcerpt(text: string | undefined, maxChars = 240): string | undefined {
+  if (!text) {
+    return undefined;
+  }
+
+  return text.length <= maxChars ? text : `${text.slice(0, maxChars).trimEnd()}…`;
+}
+
+export function buildFetchPresentation(result: FetchLike): PresentationEnvelope {
+  const wordCount = countWords(result.content?.text);
+  const fallbackPrefix = result.metadata.fallbackFrom
+    ? `${result.metadata.fallbackFrom} failed; used ${result.metadata.method} fallback. `
+    : '';
+  const compact =
+    result.status === 'ok'
+      ? `${fallbackPrefix}Fetched page · article extracted${wordCount ? ` · ${wordCount} words` : ''}`
+      : result.status === 'needs_headless'
+        ? `${fallbackPrefix}Needs headless rendering: ${result.error?.message ?? 'Headless rendering recommended.'}`
+        : `${fallbackPrefix}Fetch failed: ${result.error?.message ?? 'Unknown fetch failure.'}`;
+
+  return {
+    mode: 'compact',
+    views: {
+      compact,
+      preview: result.content?.title
+        ? `${result.content.title}\n${firstExcerpt(result.content.text) ?? ''}`.trim()
+        : firstExcerpt(result.content?.text),
+      verbose:
+        result.status === 'ok'
+          ? [
+              `URL: ${result.url}`,
+              result.content?.title ? `Title: ${result.content.title}` : undefined,
+              firstExcerpt(result.content?.text, 500)
+            ]
+              .filter(Boolean)
+              .join('\n')
+          : undefined
+    },
+    metrics: {
+      wordCount,
+      cacheHit: result.metadata.cacheHit
+    },
+    sources: [{ title: result.content?.title ?? result.url, url: result.url }]
+  };
+}

package/dist/extensions/pi-web-agent/src/presentation/search-presentation.ts

@@ -1,17 +1,29 @@
 import type { WebSearchResponse } from '../types.js';
 import type { PresentationEnvelope } from './types.js';
 
+function fanoutNote(result: WebSearchResponse): string {
+  const f = result.metadata.fanout;
+  if (!f) return '';
+  if (f.providers.length) {
+    return ` (fanout: ${f.providers.join(', ')}${f.skipped?.length ? `; skipped: ${f.skipped.join(', ')}` : ''})`;
+  }
+  if (f.skipped?.length) {
+    return ` (fanout; skipped: ${f.skipped.join(', ')})`;
+  }
+  return '';
+}
+
 function formatCompact(result: WebSearchResponse): string {
   const fallbackPrefix = result.metadata.fallbackFrom
     ? `${result.metadata.fallbackFrom} failed; used ${result.metadata.backend} fallback. `
     : '';
 
   if (result.status === 'error') {
-    return `${fallbackPrefix}Search failed: ${result.error?.message ?? 'Unknown search failure.'}`;
+    return `${fallbackPrefix}Search failed: ${result.error?.message ?? 'Unknown search failure.'}${fanoutNote(result)}`;
   }
 
   const suffix = result.results.length === 1 ? 'result' : 'results';
-  return `${fallbackPrefix}Found ${result.results.length} ${suffix}`;
+  return `${fallbackPrefix}Found ${result.results.length} ${suffix}${fanoutNote(result)}`;
 }
 
 export function buildSearchPresentation(result: WebSearchResponse): PresentationEnvelope {

package/dist/extensions/pi-web-agent/src/presentation/select-view.ts

@@ -1,20 +1,20 @@
-import type { PresentationEnvelope, PresentationMode } from './types.js';
-
-export function selectPresentationView(
-  envelope: PresentationEnvelope | undefined,
-  requestedMode: PresentationMode
-): string | undefined {
-  if (!envelope) {
-    return undefined;
-  }
-
-  if (requestedMode === 'preview' && envelope.views.preview) {
-    return envelope.views.preview;
-  }
-
-  if (requestedMode === 'verbose' && envelope.views.verbose) {
-    return envelope.views.verbose;
-  }
-
-  return envelope.views.compact;
-}
+import type { PresentationEnvelope, PresentationMode } from './types.js';
+
+export function selectPresentationView(
+  envelope: PresentationEnvelope | undefined,
+  requestedMode: PresentationMode
+): string | undefined {
+  if (!envelope) {
+    return undefined;
+  }
+
+  if (requestedMode === 'preview' && envelope.views.preview) {
+    return envelope.views.preview;
+  }
+
+  if (requestedMode === 'verbose' && envelope.views.verbose) {
+    return envelope.views.verbose;
+  }
+
+  return envelope.views.compact;
+}

package/dist/extensions/pi-web-agent/src/presentation/types.ts

@@ -1,63 +1,63 @@
-export const PRESENTATION_MODES = ['compact', 'preview', 'verbose'] as const;
-export type PresentationMode = (typeof PRESENTATION_MODES)[number];
-
-export type PresentationViews = {
-  compact: string;
-  preview?: string;
-  verbose?: string;
-};
-
-export type PresentationMetrics = {
-  durationMs?: number;
-  resultCount?: number;
-  sourceCount?: number;
-  wordCount?: number;
-  statusCode?: number;
-  cacheHit?: boolean;
-  truncated?: boolean;
-};
-
-export type PresentationSource = {
-  title: string;
-  url: string;
-  domain?: string;
-};
-
-export type PresentationEnvelope = {
-  mode: PresentationMode;
-  views: PresentationViews;
-  metrics?: PresentationMetrics;
-  sources?: PresentationSource[];
-  debug?: Record<string, unknown>;
-};
-
-export type PresentationToolName =
-  | 'web_search'
-  | 'web_fetch'
-  | 'web_fetch_headless'
-  | 'web_explore';
-
-export type PresentationScope = 'global' | 'project';
-
-export type PresentationToolOverrideMode = PresentationMode;
-
-export type PresentationToolConfig = {
-  mode: PresentationToolOverrideMode;
-};
-
-export type PresentationConfig = {
-  defaultMode: PresentationMode;
-  tools: Partial<Record<PresentationToolName, PresentationToolConfig>>;
-};
-
-export type PresentationConfigOverride = {
-  defaultMode?: PresentationMode;
-  tools: Partial<Record<PresentationToolName, PresentationToolConfig>>;
-};
-
-export type PresentationConfigFile = {
-  presentation?: {
-    defaultMode?: unknown;
-    tools?: Partial<Record<PresentationToolName, { mode?: unknown }>>;
-  };
-};
+export const PRESENTATION_MODES = ['compact', 'preview', 'verbose'] as const;
+export type PresentationMode = (typeof PRESENTATION_MODES)[number];
+
+export type PresentationViews = {
+  compact: string;
+  preview?: string;
+  verbose?: string;
+};
+
+export type PresentationMetrics = {
+  durationMs?: number;
+  resultCount?: number;
+  sourceCount?: number;
+  wordCount?: number;
+  statusCode?: number;
+  cacheHit?: boolean;
+  truncated?: boolean;
+};
+
+export type PresentationSource = {
+  title: string;
+  url: string;
+  domain?: string;
+};
+
+export type PresentationEnvelope = {
+  mode: PresentationMode;
+  views: PresentationViews;
+  metrics?: PresentationMetrics;
+  sources?: PresentationSource[];
+  debug?: Record<string, unknown>;
+};
+
+export type PresentationToolName =
+  | 'web_search'
+  | 'web_fetch'
+  | 'web_fetch_headless'
+  | 'web_explore';
+
+export type PresentationScope = 'global' | 'project';
+
+export type PresentationToolOverrideMode = PresentationMode;
+
+export type PresentationToolConfig = {
+  mode: PresentationToolOverrideMode;
+};
+
+export type PresentationConfig = {
+  defaultMode: PresentationMode;
+  tools: Partial<Record<PresentationToolName, PresentationToolConfig>>;
+};
+
+export type PresentationConfigOverride = {
+  defaultMode?: PresentationMode;
+  tools: Partial<Record<PresentationToolName, PresentationToolConfig>>;
+};
+
+export type PresentationConfigFile = {
+  presentation?: {
+    defaultMode?: unknown;
+    tools?: Partial<Record<PresentationToolName, { mode?: unknown }>>;
+  };
+};

package/dist/extensions/pi-web-agent/src/readers/github-reader.ts

@@ -0,0 +1,150 @@
+import type { WebFetchResponse } from '../types.js';
+import type { SpecialContentReader } from './types.js';
+import { READER_TEXT_CAP } from './limits.js';
+
+type GithubReaderDeps = {
+  fetchImpl?: typeof fetch;
+  token?: string;
+};
+
+function parseGithub(url: string): URL | undefined {
+  try {
+    return new URL(url);
+  } catch {
+    return undefined;
+  }
+}
+
+type GithubShape = 'blob' | 'issue' | 'pull' | 'repo-root';
+
+function classifyGithubShape(url: string): { shape: GithubShape; owner: string; repo: string; ref?: string; path?: string; num?: string } | undefined {
+  const parsed = parseGithub(url);
+  if (!parsed || parsed.hostname.toLowerCase() !== 'github.com') {
+    return undefined;
+  }
+
+  const segments = parsed.pathname.split('/').filter(Boolean);
+  const [owner, repo, type, ...rest] = segments;
+
+  // blob: [owner, repo, 'blob', ref, ...path] with rest.length >= 2
+  if (owner && repo && type === 'blob' && rest.length >= 2) {
+    const [ref, ...pathParts] = rest;
+    return { shape: 'blob', owner, repo, ref, path: pathParts.join('/') };
+  }
+
+  // issue: [owner, repo, 'issues', N]
+  if (owner && repo && type === 'issues' && rest[0]) {
+    return { shape: 'issue', owner, repo, num: rest[0] };
+  }
+
+  // pull: [owner, repo, 'pull', N]
+  if (owner && repo && type === 'pull' && rest[0]) {
+    return { shape: 'pull', owner, repo, num: rest[0] };
+  }
+
+  // repo-root: exactly [owner, repo]
+  if (owner && repo && !type) {
+    return { shape: 'repo-root', owner, repo };
+  }
+
+  return undefined;
+}
+
+function encodeSegment(segment: string): string {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(segment);
+  } catch {
+    decoded = segment;
+  }
+  return encodeURIComponent(decoded);
+}
+
+function fail(url: string, message: string): WebFetchResponse {
+  return {
+    status: 'error',
+    url,
+    metadata: { method: 'github', cacheHit: false },
+    error: { code: 'GITHUB_FETCH_FAILED', message }
+  };
+}
+
+function okResponse(url: string, title: string, text: string): WebFetchResponse {
+  const capped = text.slice(0, READER_TEXT_CAP);
+  return {
+    status: 'ok',
+    url,
+    content: { title, text: capped },
+    metadata: { method: 'github', cacheHit: false, truncated: text.length >= READER_TEXT_CAP }
+  };
+}
+
+export function createGithubReader({ fetchImpl = fetch, token = process.env.GITHUB_TOKEN }: GithubReaderDeps = {}): SpecialContentReader {
+  function headers(json: boolean): Record<string, string> {
+    const h: Record<string, string> = { 'User-Agent': 'pi-web-agent' };
+    if (json) h.Accept = 'application/vnd.github+json';
+    if (token) h.Authorization = `Bearer ${token}`;
+    return h;
+  }
+
+  async function getText(target: string): Promise<string> {
+    const res = await fetchImpl(target, { headers: headers(false) });
+    if (!res.ok) throw new Error(`GitHub returned ${res.status} for ${target}`);
+    return res.text();
+  }
+
+  async function getJson<T>(target: string): Promise<T> {
+    const res = await fetchImpl(target, { headers: headers(true) });
+    if (!res.ok) throw new Error(`GitHub API returned ${res.status} for ${target}`);
+    return res.json() as Promise<T>;
+  }
+
+  async function readBlob(url: string, owner: string, repo: string, ref: string, path: string): Promise<WebFetchResponse> {
+    const encodedPath = path.split('/').map(encodeSegment).join('/');
+    const raw = `https://raw.githubusercontent.com/${owner}/${repo}/${encodeSegment(ref)}/${encodedPath}`;
+    const text = await getText(raw);
+    return okResponse(url, `${owner}/${repo}/${path}`, text);
+  }
+
+  async function readThread(url: string, owner: string, repo: string, kind: 'issues' | 'pulls', num: string): Promise<WebFetchResponse> {
+    const base = `https://api.github.com/repos/${owner}/${repo}/${kind}/${num}`;
+    const item = await getJson<{ title?: string; body?: string }>(base);
+    const comments = await getJson<Array<{ body?: string }>>(`${base}/comments`);
+    const body = [item.body ?? '', ...comments.map((c) => c.body ?? '')].filter(Boolean).join('\n\n---\n\n');
+    return okResponse(url, item.title ?? `${owner}/${repo} ${kind} #${num}`, body);
+  }
+
+  async function readRepoRoot(url: string, owner: string, repo: string): Promise<WebFetchResponse> {
+    const readmeMeta = await getJson<{ download_url?: string }>(`https://api.github.com/repos/${owner}/${repo}/readme`);
+    const readme = readmeMeta.download_url ? await getText(readmeMeta.download_url) : '';
+    const tree = await getJson<Array<{ name: string; type: string }>>(`https://api.github.com/repos/${owner}/${repo}/contents`);
+    const listing = tree.map((entry) => `${entry.type === 'dir' ? '[dir] ' : ''}${entry.name}`).join('\n');
+    return okResponse(url, `${owner}/${repo}`, `${readme}\n\nTop-level contents:\n${listing}`);
+  }
+
+  return {
+    name: 'github',
+    canHandle(url: string): boolean {
+      return classifyGithubShape(url) !== undefined;
+    },
+    async read(url: string): Promise<WebFetchResponse> {
+      const shape = classifyGithubShape(url);
+      if (!shape) return fail(url, 'Unsupported GitHub URL shape for the reader.');
+
+      try {
+        switch (shape.shape) {
+          case 'blob':
+            return await readBlob(url, shape.owner, shape.repo, shape.ref!, shape.path!);
+          case 'issue':
+            return await readThread(url, shape.owner, shape.repo, 'issues', shape.num!);
+          case 'pull':
+            return await readThread(url, shape.owner, shape.repo, 'pulls', shape.num!);
+          case 'repo-root':
+            return await readRepoRoot(url, shape.owner, shape.repo);
+        }
+      } catch (err) {
+        return fail(url, err instanceof Error ? err.message : 'GitHub read failed.');
+      }
+    }
+  };
+}

package/dist/extensions/pi-web-agent/src/readers/limits.ts

@@ -0,0 +1,3 @@
+/** Max characters a special-content reader returns. Large enough for a typical transcript
+ *  or a medium PDF; very long documents still truncate (section-aware chunking is future work). */
+export const READER_TEXT_CAP = 24000;

package/dist/extensions/pi-web-agent/src/readers/pdf-reader.ts

@@ -0,0 +1,87 @@
+import { extractText, getDocumentProxy, getMeta } from 'unpdf';
+import type { WebFetchResponse } from '../types.js';
+import type { SpecialContentReader } from './types.js';
+import { READER_TEXT_CAP } from './limits.js';
+
+type PdfReaderDeps = {
+  fetchImpl?: typeof fetch;
+  /** Injectable for tests; defaults to unpdf. */
+  extractPdfText?: (bytes: Uint8Array) => Promise<{ text: string; title?: string }>;
+};
+
+async function defaultExtract(bytes: Uint8Array): Promise<{ text: string; title?: string }> {
+  const pdf = await getDocumentProxy(bytes);
+  const [{ text }, meta] = await Promise.all([
+    extractText(pdf, { mergePages: true }),
+    getMeta(pdf).catch(() => ({ info: undefined }))
+  ]);
+  const info = (meta as { info?: { Title?: string } }).info;
+  const rawTitle = info?.Title?.trim();
+  return { text, title: rawTitle ? rawTitle : undefined };
+}
+
+function isPdfUrl(url: string): boolean {
+  try {
+    return new URL(url).pathname.toLowerCase().endsWith('.pdf');
+  } catch {
+    return false;
+  }
+}
+
+function filenameFromUrl(url: string): string {
+  try {
+    const last = new URL(url).pathname.split('/').filter(Boolean).pop() ?? 'PDF';
+    return decodeURIComponent(last);
+  } catch {
+    return 'PDF';
+  }
+}
+
+export function createPdfReader({ fetchImpl = fetch, extractPdfText = defaultExtract }: PdfReaderDeps = {}): SpecialContentReader {
+  return {
+    name: 'pdf',
+    canHandle: isPdfUrl,
+    canHandleContentType(contentType: string): boolean {
+      return contentType.toLowerCase().includes('application/pdf');
+    },
+    async read(url: string): Promise<WebFetchResponse> {
+      try {
+        const response = await fetchImpl(url);
+        if (!('ok' in response) || !response.ok) {
+          return {
+            status: 'error',
+            url,
+            metadata: { method: 'pdf', cacheHit: false },
+            error: { code: 'PDF_READ_FAILED', message: `Fetching the PDF failed.` }
+          };
+        }
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        const extracted = await extractPdfText(bytes);
+        const text = extracted.text.trim();
+
+        if (text.length === 0) {
+          return {
+            status: 'unsupported',
+            url,
+            metadata: { method: 'pdf', cacheHit: false, contentType: 'application/pdf' },
+            error: { code: 'PDF_NO_TEXT', message: 'This looks like a scanned PDF with no extractable text.' }
+          };
+        }
+
+        return {
+          status: 'ok',
+          url,
+          content: { title: extracted.title ?? filenameFromUrl(url), text: text.slice(0, READER_TEXT_CAP) },
+          metadata: { method: 'pdf', cacheHit: false, contentType: 'application/pdf', truncated: text.length >= READER_TEXT_CAP }
+        };
+      } catch (err) {
+        return {
+          status: 'error',
+          url,
+          metadata: { method: 'pdf', cacheHit: false },
+          error: { code: 'PDF_READ_FAILED', message: err instanceof Error ? err.message : 'PDF read failed.' }
+        };
+      }
+    }
+  };
+}

package/dist/extensions/pi-web-agent/src/readers/resolver.ts

@@ -0,0 +1,25 @@
+import type { WebFetchResponse } from '../types.js';
+import type { SpecialContentReader } from './types.js';
+
+type ResolverDeps = {
+  readers: SpecialContentReader[];
+  fallback: (input: { url: string }) => Promise<WebFetchResponse>;
+};
+
+export function createSpecialContentResolver({ readers, fallback }: ResolverDeps) {
+  return async function resolve(input: { url: string }): Promise<WebFetchResponse> {
+    const matched = readers.find((reader) => reader.canHandle(input.url));
+    if (matched) {
+      return matched.read(input.url);
+    }
+
+    const response = await fallback(input);
+    if (response.status === 'unsupported' && response.metadata.contentType) {
+      const byContentType = readers.find((reader) => reader.canHandleContentType?.(response.metadata.contentType!));
+      if (byContentType) {
+        return byContentType.read(input.url);
+      }
+    }
+    return response;
+  };
+}

package/dist/extensions/pi-web-agent/src/readers/types.ts

@@ -0,0 +1,11 @@
+import type { WebFetchResponse } from '../types.js';
+
+export type SpecialContentReader = {
+  name: string;
+  /** Cheap URL-shape check. No network. */
+  canHandle(url: string): boolean;
+  /** Optional: claim a response by content-type after a normal fetch (e.g. application/pdf). */
+  canHandleContentType?(contentType: string): boolean;
+  /** Produce a normal WebFetchResponse. Must never throw. */
+  read(url: string): Promise<WebFetchResponse>;
+};

package/dist/extensions/pi-web-agent/src/readers/youtube-reader.ts

@@ -0,0 +1,79 @@
+import { getSubtitles, getVideoDetails } from 'youtube-caption-extractor';
+import type { WebFetchResponse } from '../types.js';
+import type { SpecialContentReader } from './types.js';
+import { READER_TEXT_CAP } from './limits.js';
+
+type Subtitle = { start: string; dur: string; text: string };
+type YoutubeReaderDeps = {
+  fetchSubtitles?: (input: { videoID: string; lang: string }) => Promise<Subtitle[]>;
+  fetchDetails?: (input: { videoID: string; lang: string }) => Promise<{ title?: string; description?: string }>;
+};
+
+function extractVideoId(url: string): string | undefined {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return undefined;
+  }
+  const host = parsed.hostname.toLowerCase().replace(/^www\./, '');
+  if (host === 'youtu.be') {
+    return parsed.pathname.split('/').filter(Boolean)[0];
+  }
+  if (host === 'youtube.com') {
+    if (parsed.pathname === '/watch') return parsed.searchParams.get('v') ?? undefined;
+    const [prefix, id] = parsed.pathname.split('/').filter(Boolean);
+    if ((prefix === 'shorts' || prefix === 'live' || prefix === 'embed') && id) return id;
+  }
+  return undefined;
+}
+
+export function createYoutubeReader({ fetchSubtitles = getSubtitles, fetchDetails = getVideoDetails }: YoutubeReaderDeps = {}): SpecialContentReader {
+  return {
+    name: 'youtube',
+    canHandle(url: string): boolean {
+      return extractVideoId(url) !== undefined;
+    },
+    async read(url: string): Promise<WebFetchResponse> {
+      const videoID = extractVideoId(url);
+      if (!videoID) {
+        return {
+          status: 'error',
+          url,
+          metadata: { method: 'youtube', cacheHit: false },
+          error: { code: 'YOUTUBE_READ_FAILED', message: 'Could not extract a video id.' }
+        };
+      }
+      try {
+        const [subtitles, details] = await Promise.all([
+          fetchSubtitles({ videoID, lang: 'en' }),
+          fetchDetails({ videoID, lang: 'en' }).catch(() => ({ title: undefined }))
+        ]);
+
+        if (!subtitles || subtitles.length === 0) {
+          return {
+            status: 'unsupported',
+            url,
+            metadata: { method: 'youtube', cacheHit: false },
+            error: { code: 'YOUTUBE_NO_CAPTIONS', message: 'No captions available for this video.' }
+          };
+        }
+
+        const transcript = subtitles.map((line) => line.text).join(' ').replace(/\s+/g, ' ').trim();
+        return {
+          status: 'ok',
+          url,
+          content: { title: details.title ?? `YouTube ${videoID}`, text: transcript.slice(0, READER_TEXT_CAP) },
+          metadata: { method: 'youtube', cacheHit: false, truncated: transcript.length >= READER_TEXT_CAP }
+        };
+      } catch (err) {
+        return {
+          status: 'error',
+          url,
+          metadata: { method: 'youtube', cacheHit: false },
+          error: { code: 'YOUTUBE_READ_FAILED', message: err instanceof Error ? err.message : 'YouTube read failed.' }
+        };
+      }
+    }
+  };
+}