@selesai/code 0.13.3 → 0.13.4

package/dist/extensions/pi-web-agent/src/orchestration/research-orchestrator.ts

@@ -1,4 +1,4 @@
-import type { WebFetchHeadlessResponse, WebFetchResponse } from '../types.js';
+import type { SearchProviderName, WebFetchHeadlessResponse, WebFetchResponse } from '../types.js';
 import { rankEvidence } from './evidence-ranker.js';
 import { planSearchQueries } from './query-planner.js';
 import { classifySourceProfile } from './source-profile.js';
@@ -25,6 +25,10 @@ function summarizeText(text: string, maxLength = 180): string {
   return text.replace(/\s+/g, ' ').trim().slice(0, maxLength);
 }
 
+function isReaderMethod(method: string): boolean {
+  return method === 'github' || method === 'pdf' || method === 'youtube';
+}
+
 function isBotCheckContent({ title = '', text }: { title?: string; text: string }) {
   return /performing security verification|security service|verify you are not a bot|just a moment|checking your browser/i.test(
     `${title}\n${text}`
@@ -35,6 +39,17 @@ function evidenceFromFetch(result: WebFetchResponse): ResearchEvidence | null {
   if (result.status !== 'ok' || !result.content?.text.trim()) return null;
   if (isBotCheckContent({ title: result.content.title, text: result.content.text })) return null;
 
+  if (isReaderMethod(result.metadata.method)) {
+    return {
+      title: result.content.title ?? result.url,
+      url: result.url,
+      sourceKind: 'primary-content',
+      method: result.metadata.method,
+      summary: result.content.text,
+      supports: [result.content.text]
+    };
+  }
+
   return {
     title: result.content.title ?? result.url,
     url: result.url,
@@ -101,7 +116,9 @@ function buildMetadata({
   allLowValueOutcomes,
   headlessAttempts,
   exhaustedBudget,
-  caveatReasons = []
+  caveatReasons = [],
+  fanoutProviders,
+  fanoutSkipped
 }: {
   previousQueries: string[];
   allEvidence: ResearchEvidence[];
@@ -110,13 +127,17 @@ function buildMetadata({
   headlessAttempts: number;
   exhaustedBudget: boolean;
   caveatReasons?: EvidenceCaveatReason[];
+  fanoutProviders?: SearchProviderName[];
+  fanoutSkipped?: SearchProviderName[];
 }) {
   return {
     searchPasses: previousQueries.length,
     fetchedPages: allEvidence.length + allGaps.length + allLowValueOutcomes.length,
     headlessAttempts,
     exhaustedBudget,
-    caveatReasons
+    caveatReasons,
+    fanoutProviders,
+    fanoutSkipped
   };
 }
 
@@ -170,6 +191,14 @@ export function createResearchOrchestrator({
       const suggestedHeadlessUrls: string[] = [];
       let headlessAttempts = 0;
       let lastPass: ResearchWorkerResult | undefined;
+      const fanoutProvidersSeen = new Set<SearchProviderName>();
+      const fanoutSkippedSeen = new Set<SearchProviderName>();
+
+      function fanoutSnapshot() {
+        const providers = fanoutProvidersSeen.size ? [...fanoutProvidersSeen] : undefined;
+        const skipped = [...fanoutSkippedSeen].filter((p) => !fanoutProvidersSeen.has(p));
+        return { fanoutProviders: providers, fanoutSkipped: skipped.length ? skipped : undefined };
+      }
 
       if (fetchDirect) {
         for (const url of extractDirectUrls(query).slice(0, 3)) {
@@ -204,6 +233,36 @@ export function createResearchOrchestrator({
         }
       }
 
+      if (allEvidence.some((item) => item.sourceKind === 'primary-content')) {
+        const ranked = rankEvidence(allEvidence.filter((item) => item.sourceKind !== 'package-page'));
+        const quality = analyzeEvidenceQuality({
+          evidence: ranked,
+          gaps: allGaps,
+          lowValueOutcomes: allLowValueOutcomes
+        });
+        return {
+          decision: decisionForAnswer({ action: 'answer', query, ranked, exhaustedBudget: false }),
+          evidence: ranked,
+          workerPass: combinedWorkerPass({
+            lastPass,
+            previousQueries,
+            allGaps,
+            allLowValueOutcomes,
+            exhaustedBudget: false
+          }),
+          metadata: buildMetadata({
+            previousQueries,
+            allEvidence,
+            allGaps,
+            allLowValueOutcomes,
+            headlessAttempts,
+            exhaustedBudget: false,
+            caveatReasons: quality.caveatReasons,
+            ...fanoutSnapshot()
+          })
+        };
+      }
+
       for (let passIndex = 0; passIndex < DEFAULT_MAX_PASSES; passIndex++) {
         const queries = planSearchQueries({
           originalQuery: query,
@@ -221,6 +280,8 @@ export function createResearchOrchestrator({
           });
 
           lastPass = pass;
+          pass.fanoutProviders?.forEach((p) => fanoutProvidersSeen.add(p));
+          pass.fanoutSkipped?.forEach((p) => fanoutSkippedSeen.add(p));
           allEvidence.push(...pass.evidence);
           allGaps.push(...pass.gaps);
           allLowValueOutcomes.push(...pass.lowValueOutcomes);
@@ -287,7 +348,8 @@ export function createResearchOrchestrator({
                   allLowValueOutcomes,
                   headlessAttempts,
                   exhaustedBudget,
-                  caveatReasons: updatedQuality.caveatReasons
+                  caveatReasons: updatedQuality.caveatReasons,
+                  ...fanoutSnapshot()
                 })
               };
             }
@@ -314,7 +376,8 @@ export function createResearchOrchestrator({
                 allLowValueOutcomes,
                 headlessAttempts,
                 exhaustedBudget: false,
-                caveatReasons: quality.caveatReasons
+                caveatReasons: quality.caveatReasons,
+                ...fanoutSnapshot()
               })
             };
           }
@@ -338,7 +401,8 @@ export function createResearchOrchestrator({
                 allLowValueOutcomes,
                 headlessAttempts,
                 exhaustedBudget,
-                caveatReasons: quality.caveatReasons
+                caveatReasons: quality.caveatReasons,
+                ...fanoutSnapshot()
               })
             };
           }
@@ -368,7 +432,8 @@ export function createResearchOrchestrator({
           allLowValueOutcomes,
           headlessAttempts,
           exhaustedBudget: true,
-          caveatReasons: quality.caveatReasons
+          caveatReasons: quality.caveatReasons,
+          ...fanoutSnapshot()
         })
       };
     }

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

@@ -1,4 +1,7 @@
+import type { SearchProviderName } from '../types.js';
+
 export type ResearchSourceKind =
+  | 'primary-content'
   | 'official-docs'
   | 'official-api'
   | 'official-discussion'
@@ -7,7 +10,7 @@ export type ResearchSourceKind =
   | 'package-page'
   | 'other';
 
-export type ResearchMethod = 'search' | 'http' | 'headless' | 'firecrawl';
+export type ResearchMethod = 'search' | 'http' | 'headless' | 'firecrawl' | 'github' | 'pdf' | 'youtube';
 
 export type ResearchEvidence = {
   title: string;
@@ -36,6 +39,8 @@ export type ResearchWorkerResult = {
   lowValueOutcomes: ResearchLowValueOutcome[];
   suggestedHeadlessUrl?: string;
   exhaustedBudget: boolean;
+  fanoutProviders?: SearchProviderName[];
+  fanoutSkipped?: SearchProviderName[];
 };
 
 export type ResearchRunMetadata = {
@@ -43,6 +48,8 @@ export type ResearchRunMetadata = {
   fetchedPages: number;
   headlessAttempts: number;
   exhaustedBudget: boolean;
+  fanoutProviders?: SearchProviderName[];
+  fanoutSkipped?: SearchProviderName[];
 };
 
 export type ResearchOrchestratorDecision =

package/dist/extensions/pi-web-agent/src/orchestration/research-worker.ts

@@ -17,6 +17,10 @@ function summarizeText(text: string, maxLength = 180): string {
   return text.replace(/\s+/g, ' ').trim().slice(0, maxLength);
 }
 
+function isReaderMethod(method: string): boolean {
+  return method === 'github' || method === 'pdf' || method === 'youtube';
+}
+
 function isBotCheckContent({ title = '', text }: { title?: string; text: string }) {
   return /performing security verification|security service|verify you are not a bot|just a moment|checking your browser/i.test(
     `${title}\n${text}`
@@ -28,6 +32,19 @@ function evidenceFromFetch(fetched: WebFetchResponse, fallbackTitle: string) {
   if (fetched.status !== 'ok' || !content) return null;
   if (isBotCheckContent({ title: content.title, text: content.text })) return null;
 
+  // A successful reader read with usable text is primary content, exempt from the
+  // package-page filter below.
+  if (isReaderMethod(fetched.metadata.method) && content.text.trim()) {
+    return {
+      title: content.title ?? fallbackTitle,
+      url: fetched.url,
+      sourceKind: 'primary-content',
+      method: fetched.metadata.method,
+      summary: content.text,
+      supports: [content.text]
+    } satisfies ResearchEvidence;
+  }
+
   const sourceKind = classifySource(fetched.url);
   if (sourceKind === 'package-page') {
     return null;
@@ -98,6 +115,8 @@ export function createResearchWorker({
       }
 
       const searchResult = await search({ query });
+      const fanoutProviders = searchResult.metadata.fanout?.providers;
+      const fanoutSkipped = searchResult.metadata.fanout?.skipped;
       if (searchResult.status !== 'ok') {
         return {
           searchQueries,
@@ -110,7 +129,9 @@ export function createResearchWorker({
           ],
           lowValueOutcomes,
           suggestedHeadlessUrl,
-          exhaustedBudget: false
+          exhaustedBudget: false,
+          fanoutProviders,
+          fanoutSkipped
         };
       }
 
@@ -126,7 +147,9 @@ export function createResearchWorker({
             }
           ],
           suggestedHeadlessUrl,
-          exhaustedBudget: false
+          exhaustedBudget: false,
+          fanoutProviders,
+          fanoutSkipped
         };
       }
 
@@ -174,7 +197,9 @@ export function createResearchWorker({
         gaps,
         lowValueOutcomes,
         suggestedHeadlessUrl,
-        exhaustedBudget: false
+        exhaustedBudget: false,
+        fanoutProviders,
+        fanoutSkipped
       };
     }
   };

package/dist/extensions/pi-web-agent/src/orchestration/source-profile.ts

@@ -32,6 +32,10 @@ function parseUrl(rawUrl: string): URL | undefined {
   }
 }
 
+export function hostOf(rawUrl: string): string | undefined {
+  return parseUrl(rawUrl)?.hostname.toLowerCase().replace(/^www\./, '');
+}
+
 function isOfficialApi(host: string, path: string) {
   return (
     (host === 'playwright.dev' && path.startsWith('/docs/api/')) ||

package/dist/extensions/pi-web-agent/src/orchestration/url.ts

@@ -0,0 +1,35 @@
+const TRACKING_PARAMS = new Set([
+  'utm_source',
+  'utm_medium',
+  'utm_campaign',
+  'utm_term',
+  'utm_content',
+  'utm_name',
+  'fbclid',
+  'gclid'
+]);
+
+/** Canonical form for dedupe/comparison. Returns undefined for non-http(s) or unparseable input. */
+export function canonicalizeUrl(raw: string, options: { canonicalizeHost?: boolean } = {}): string | undefined {
+  const { canonicalizeHost = true } = options;
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return undefined;
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return undefined;
+
+  if (canonicalizeHost) {
+    url.hostname = url.hostname.replace(/^www\./, '');
+  }
+  for (const key of [...url.searchParams.keys()]) {
+    if (TRACKING_PARAMS.has(key.toLowerCase())) {
+      url.searchParams.delete(key);
+    }
+  }
+  url.hash = '';
+  return url.toString().replace(/\/$/, '');
+}
+
+export { TRACKING_PARAMS };

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

@@ -1,10 +1,13 @@
-import type { WebExploreResponse } from '../types.js';
+import type { FetchMethod, WebExploreResponse } from '../types.js';
 import type { PresentationEnvelope } from './types.js';
 
-function internalReaderLabel(method?: 'http' | 'headless' | 'firecrawl') {
+function internalReaderLabel(method?: FetchMethod) {
   if (method === 'headless') return 'web_fetch_headless';
   if (method === 'firecrawl') return 'firecrawl';
   if (method === 'http') return 'web_fetch';
+  if (method === 'github') return 'github';
+  if (method === 'pdf') return 'pdf';
+  if (method === 'youtube') return 'youtube';
   return 'web_explore';
 }
 
@@ -18,8 +21,15 @@ export function buildExplorePresentation(result: WebExploreResponse): Presentati
     };
   }
 
+  const fanoutProviders = result.metadata?.fanoutProviders;
+  const fanoutSkipped = result.metadata?.fanoutSkipped;
+  const fanoutNote = fanoutProviders?.length
+    ? ` (fanout: ${fanoutProviders.join(', ')}${fanoutSkipped?.length ? `; skipped: ${fanoutSkipped.join(', ')}` : ''})`
+    : fanoutSkipped?.length
+      ? ` (fanout; skipped: ${fanoutSkipped.join(', ')})`
+      : '';
   const internalSummary = result.metadata
-    ? `Internal research: web_search ×${result.metadata.searchPasses}, web_fetch ×${result.metadata.fetchedPages}, web_fetch_headless ×${result.metadata.headlessAttempts}`
+    ? `Internal research: web_search ×${result.metadata.searchPasses}${fanoutNote}, web_fetch ×${result.metadata.fetchedPages}, web_fetch_headless ×${result.metadata.headlessAttempts}`
     : undefined;
   const hasEvidence = result.findings.length > 0 || result.sources.length > 0;
   const evidenceLines = hasEvidence
@@ -43,12 +53,14 @@ export function buildExplorePresentation(result: WebExploreResponse): Presentati
     .filter((line) => line !== undefined)
     .join('\n');
 
+  const compact = hasEvidence
+    ? `Reviewed ${result.sources.length} sources · synthesized answer with ${result.findings.length} findings`
+    : 'No usable evidence found';
+
   return {
     mode: 'compact',
     views: {
-      compact: hasEvidence
-        ? `Reviewed ${result.sources.length} sources · synthesized answer with ${result.findings.length} findings`
-        : 'No usable evidence found',
+      compact,
       preview,
       verbose
     },

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/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>;
+};