@lincoln504/pi-research 1.5.3 → 1.6.1

package/src/orchestration/quick-research-orchestrator.ts

@@ -17,8 +17,8 @@ import { recordLlmUsage } from '../utils/llm-usage.ts';
 import { logger } from '../logger.ts';
 import { getConfig, type Config } from '../config.ts';
 import { createResearcherSession } from './researcher.ts';
-import { ensureAssistantResponse, parseCitations } from '../utils/text-utils.ts';
-import { getMaxScrapeBatches, resolveExcludedTools } from '../constants.ts';
+import { ensureAssistantResponse, parseCitations, isAnalysisFreeSynthesis, synthesisProseBody, stripReportPreamble } from '../utils/text-utils.ts';
+import { getMaxScrapeBatches, resolveExcludedTools, QUICK_THIN_REPORT_NOTICE } from '../constants.ts';
 import { resolveResearchModel, isPromptCachingActiveForModel } from '../core/llm/research-model-resolver.ts';
 import type { ResearchObserver } from '../core/interfaces/observer-interfaces.ts';
 import { HeadlessObserver, makeSafeObserver, type HeadlessObserverOptions } from './headless-observer.ts';
@@ -354,6 +354,44 @@ export class QuickResearchOrchestrator {
           // digest out of the delivered document.
           result = synthesisService.getReport(this.options.researchId, 'quick') ?? result;
 
+          // Drop a leading line that announces the report instead of being part of it
+          // ("I have gathered sufficient material… I will now synthesize the full
+          // report."). The prompt forbids it and the instruction is not reliably obeyed;
+          // quick mode has nothing behind it to absorb the line, so it lands as the
+          // reader's first sentence. Removed BEFORE the analysis check below, so that
+          // check measures the report rather than the narration about it.
+          const { body: withoutPreamble, preamble } = stripReportPreamble(result);
+          if (preamble) {
+            logger.debug(`[QuickOrchestrator] Dropped a ${preamble.length}-char narration preamble from the report: ${preamble.slice(0, 120)}`);
+            metrics.increment('research_report_preamble_stripped_total', 1, { mode: 'quick' });
+            result = withoutPreamble;
+          }
+
+          // Same disguise as the deep path, and here it is the DELIVERABLE: a report with
+          // no analysis in it — a bare heading, a fragment — is about to have the rebuilt
+          // source list appended below, which pads it to kilobytes and makes a failed run
+          // read as a complete one. Quick mode has no second layer of researcher reports to
+          // fall back on, so the honest response is to say so in the report itself rather
+          // than hand back a heading over a link dump and call it a success.
+          //
+          // The VOLUME signal is deliberately disabled here (0). The 800-character floor was
+          // calibrated on deep reports; quick mode answers a single question and a correct
+          // reply can legitimately be one sentence, and there is no measured distribution of
+          // quick-report lengths to justify any floor. Since the only available response is
+          // a warning, a false positive would tell a user their correct answer is untrustworthy
+          // — strictly worse than missing a thin one. The structural signal is length-independent
+          // and carries no such risk: "Paris is the capital of France." ends a sentence and
+          // passes, a bare title does not and is flagged.
+          //
+          // Added to the body BEFORE ensureCitedLinks so the links land beneath it — the
+          // same ordering constraint the weak-grounding notice observes, because
+          // parseCitations absorbs any text trailing the last entry into its description.
+          if (isAnalysisFreeSynthesis(result, 0)) {
+            logger.warn(`[QuickOrchestrator] Report contains no complete sentence (${synthesisProseBody(result).length} char(s) of prose) — flagging it in the report`);
+            metrics.increment('research_synthesis_analysis_free_total', 1, { mode: 'quick' });
+            result = `${result.trim()}\n\n${QUICK_THIN_REPORT_NOTICE}`;
+          }
+
           // Ensure CITED LINKS section is accurate and consistent
           result = synthesisService.ensureCitedLinks(this.options.researchId, result);
           // Snapshot BEFORE steering guidance is appended: parseCitations absorbs

package/src/orchestration/research-synthesis-service.ts

@@ -277,7 +277,12 @@ export class ResearchSynthesisService implements IService {
     if (reportCount === 0) {
       synthesis += 'No researcher reports were generated before the process stopped.';
     } else {
-      synthesis += `This is an automated synthesis of ${reportCount} individual researcher report(s) gathered before the process was interrupted.\n\n`;
+      // Neutral about WHY the synthesis step produced nothing usable, because there are
+      // now two callers: a run interrupted mid-flight, and one whose synthesis LLM returned
+      // a report with no analysis in it. Asserting an interruption would be inaccurate for
+      // the second, and telling a user the run was interrupted when it was not is exactly
+      // the kind of misleading output this fallback exists to avoid.
+      synthesis += `This is an automated compilation of ${reportCount} individual researcher report(s). The synthesis step did not produce a usable summary for this run, so the findings are presented as collected.\n\n`;
       synthesis += Array.from(reports.entries())
         .map(([id, report]) => `Researcher ${id}\n\n${report}`)
         .join('\n\n');

package/src/prompts/researcher.md

@@ -62,6 +62,8 @@ Write your report immediately after scraping is complete, or as soon as a tool r
 ## Report Format
 
 {{digest_section}}
+Emit the report and nothing else. No preamble, and no narration of what you are about to do — not "I have gathered extensive material…", not "Let me now synthesize my findings…". Begin at the report's own first line.
+
 Use [N] inline citations throughout. Write in plain prose — no markdown headings, no bullet points, no bold or italic text. Use clear paragraphs separated by blank lines. The full CITED LINKS list goes at the very end.
 
 [Topic Title]

package/src/utils/text-utils.ts

@@ -280,6 +280,105 @@ export function lastCitedLinksHeader(text: string): { lineStart: number; textSta
   return { lineStart, textStart };
 }
 
+/**
+ * A first-person opener that announces the report instead of being part of it:
+ * "I have gathered extensive material… Let me now synthesize my findings into a
+ * comprehensive report."
+ *
+ * Deliberately narrow. It has to match a line that is BOTH first-person AND about the
+ * act of reporting, because the only available response is to delete the line, and the
+ * cost of deleting a real one is losing content nothing else can recover.
+ */
+const REPORT_NARRATION_OPENER = /^(?:I|I'll|I'm|Let me|Now I|Next I|First,? I)\b/i;
+const REPORT_NARRATION_SUBJECT =
+  /\b(?:report|synthesi[sz]\w*|findings|material|sources|scraped|gathered|research\w*|summar\w+)\b/i;
+
+/**
+ * Remove a leading line that narrates the report rather than being part of it.
+ *
+ * The researcher prompt forbids this, and the instruction is not reliably obeyed: across
+ * live quick runs the delivered document repeatedly opened with "I have gathered
+ * sufficient material… I will now synthesize the full report." Quick mode has no
+ * synthesis step behind it to absorb that, so it reaches the reader as the report's
+ * first line.
+ *
+ * Every condition here narrows a DESTRUCTIVE action, so each one is required rather than
+ * scored: the segment must be a single line, must be separated from the report by a
+ * blank line, must read as first-person narration ABOUT reporting, and must leave
+ * something behind. A report that opens correctly — with a topic title, as the format
+ * requires — matches none of them.
+ *
+ * @returns the body with the preamble removed, and the preamble itself (empty when
+ *          nothing was stripped) so callers can log and count what they dropped.
+ */
+export function stripReportPreamble(text: string): { body: string; preamble: string } {
+  const trimmed = text.trimStart();
+  const breakAt = trimmed.indexOf('\n\n');
+  if (breakAt < 0) return { body: text, preamble: '' };
+
+  const head = trimmed.slice(0, breakAt).trim();
+  const rest = trimmed.slice(breakAt + 2).trimStart();
+  if (head.includes('\n')) return { body: text, preamble: '' };
+  // Something has to be left. There is deliberately no LENGTH floor beyond that: a
+  // short remainder is the answer ("Paris is the capital of France."), and keeping the
+  // narration to pad it out would both deliver the wrong text and let that narration's
+  // full stop satisfy the analysis check that runs on the result.
+  if (!rest) return { body: text, preamble: '' };
+  if (!REPORT_NARRATION_OPENER.test(head)) return { body: text, preamble: '' };
+  if (!REPORT_NARRATION_SUBJECT.test(head)) return { body: text, preamble: '' };
+
+  return { body: rest, preamble: head };
+}
+
+/**
+ * The prose body of a synthesis: everything before its CITED LINKS section, trimmed.
+ * Returns the whole text when there is no such section.
+ *
+ * Exists to measure how much the model ACTUALLY wrote. Length alone cannot do that,
+ * because the engine rebuilds and appends the citation list itself — a report whose
+ * body is one title line still comes out kilobytes long once that block lands, which
+ * is precisely how a synthesis containing no analysis reached users looking complete.
+ */
+export function synthesisProseBody(text: string): string {
+  const { lineStart } = lastCitedLinksHeader(text);
+  return (lineStart < 0 ? text : text.slice(0, lineStart)).trim();
+}
+
+/**
+ * Whether a synthesis carries no actual analysis — a heading with nothing under it,
+ * a stray sentence fragment, or an empty string.
+ *
+ * Two INDEPENDENT signals, either of which is enough, so the check does not rest on a
+ * single tuned number:
+ *
+ *  - Volume. Less prose than a real report could possibly contain. Pass 0 to DISABLE
+ *    this signal, which callers must do wherever no length data justifies a floor:
+ *    a wrongly-flagged report is worse than a missed one when the only available
+ *    response is to warn the reader about output that is actually fine.
+ *  - Structure. No sentence ever ends. Every observed failure was a bare title line,
+ *    which has no terminator at all; any genuine report has many. This one needs no
+ *    threshold and would catch a title of any length.
+ *
+ * Measured on the prose only — the text before CITED LINKS — because the engine
+ * rebuilds and appends the source list itself, which pads a one-line failure out to
+ * kilobytes and is exactly how such a report reached users looking complete.
+ */
+export function isAnalysisFreeSynthesis(text: string, minProseChars: number): boolean {
+  const prose = synthesisProseBody(text);
+  // Drop markdown heading markers and blockquote/bold decoration before judging, so a
+  // model that writes "## Title" is measured the same as one that writes "Title".
+  const stripped = prose.replace(/^[ \t]*(?:#{1,6}[ \t]*|>[ \t]*|\*\*)/gm, '').trim();
+  if (minProseChars > 0 && stripped.length < minProseChars) return true;
+  // A report with no sentence-ending punctuation anywhere is a heading, a fragment or a
+  // list of bare labels — never analysis. The terminator set must not assume Latin
+  // punctuation: a report written in a script that ends sentences with a danda, an
+  // Arabic full stop or a CJK full stop is a correct report, and this signal is the only
+  // one quick mode runs, where a false positive tells the reader a good answer is
+  // untrustworthy.
+  if (!/[.!?。！？।॥۔؟።]/.test(stripped)) return true;
+  return false;
+}
+
 /**
  * Parses the CITED LINKS section from a researcher report, extracting URLs, sources, and their descriptions.
  * Handles both single-line 'URL - description' and multi-line 'Source:'/'Description:' formats.

package/src/web-research/scraper-utils.ts

@@ -19,45 +19,13 @@ import {
   INTERNAL_NETWORK_PATTERNS,
   type NativeHtmlToMarkdownModule,
 } from './scraper-types.ts';
-import { isCloudflareBlockError, isTaskTimeoutError, isPoolShutdownError } from '../infrastructure/browser/browser-error-utils.ts';
 
 /**
- * True when a scrape failure is an EXPECTED per-URL outcome rather than an engine
- * fault. Scraping the open web routinely hits bot-protection interstitials, thin
- * "stub" pages, HTTP 4xx/5xx, slow/unresponsive remotes, and (on quit) pool-drain
- * races. None of these is a pi-research bug: the URL is already accounted for as
- * "not scraped" (scrape_results_total{outcome=total_failure}) and surfaced to the
- * user that way, and no operator action follows. Callers use this to log such
- * failures at debug instead of error — keeping the ERROR log (and, via
- * logger.error's error-tracker re-track, the diagnostic error count) focused on
- * genuine faults. The messages matched here are produced by validateContent
- * (`Fetch blocked:` / `Fetch returned stub:`), scrapeWithFetch (`HTTP <code>`)
- * and extractPdfToMarkdown (`Could not extract content from PDF`, `PDF too
- * large`) — a malformed/encrypted/scanned-image-only PDF, or one that simply
- * exceeds the deliberate 100MB policy cap, is routine on the open web and
- * just as non-actionable as a stub page or a 404; the 25MB HTML policy caps
- * (`HTML response too large` from the fetch layer, `Browser HTML too large`
- * from the browser layer) are the same deliberate-cap class; the remaining
- * cases delegate to the shared browser-layer predicates. Deliberately does NOT
- * match 'PDF extraction unavailable' (a pdf-oxide-wasm native-module load
- * failure) — that is an infrastructure fault affecting every URL, not a
- * routine per-PDF outcome, and must still surface at ERROR.
+ * Re-exported from the browser error utilities, where it lives beside the three
+ * predicates it delegates to. Kept exported here because this is where every scrape
+ * caller already imports its error helpers from.
  */
-export function isBenignScrapeFailure(error: unknown): boolean {
-  const msg = error instanceof Error ? error.message : String(error);
-  return (
-    msg.startsWith('Fetch blocked:') ||                  // bot-protection interstitial (Cloudflare, DDoS-Guard, …)
-    msg.startsWith('Fetch returned stub:') ||             // nav-only / near-empty page
-    msg.startsWith('Could not extract content from PDF') || // malformed/encrypted/scanned-only PDF
-    msg.startsWith('PDF too large') ||                    // exceeds the deliberate 100MB policy cap
-    msg.startsWith('HTML response too large') ||          // fetch-layer 25MB policy cap — same class as the PDF cap
-    msg.startsWith('Browser HTML too large') ||           // browser-layer 25MB policy cap
-    /^HTTP \d{3}\b/.test(msg) ||                          // remote 4xx/5xx status
-    isCloudflareBlockError(error) ||
-    isTaskTimeoutError(error) ||
-    isPoolShutdownError(error)
-  );
-}
+export { isBenignScrapeFailure } from '../infrastructure/browser/browser-error-utils.ts';
 
 /**
  * Get a random user agent

package/src/youtube/potoken.ts

@@ -6,8 +6,8 @@
  * HTTP 200 with an EMPTY body (a silent failure). This module mints tokens with
  * `bgutils-js`, running the BotGuard VM under a `jsdom` DOM.
  *
- * Hard-won implementation details (validated live against youtubei.js@17 /
- * bgutils-js@3 / jsdom@29):
+ * Hard-won implementation details (re-validated live against youtubei.js@18 /
+ * bgutils-js@4 / jsdom@29):
  *
  *  1. Cross-realm typed arrays. The BotGuard VM must run in the SAME JS realm as
  *     bgutils' `base64ToU8` (the Node realm). So the interpreter is eval'd via
@@ -171,9 +171,17 @@ async function doMint(
   const started = Date.now();
 
   // Lazy-load heavy deps — never imported at module load (keeps startup native-free).
-  const bgMod = (await import('bgutils-js')) as unknown as BgModule;
-  const BG = bgMod.BG ?? bgMod.default;
-  const { buildURL, getHeaders } = bgMod;
+  // bgutils-js 4 dropped the barrel entry (package.json "exports" has no "."), so each
+  // piece comes from its own subpath: the challenge fetcher and VM client from
+  // /botguard, the minter from /webpo, the attestation URL/header helpers from /utils.
+  const [bgGuard, bgWebPo, bgUtils] = (await Promise.all([
+    import('bgutils-js/botguard'),
+    import('bgutils-js/webpo'),
+    import('bgutils-js/utils'),
+  ])) as unknown as [BgGuardModule, BgWebPoModule, BgUtilsModule];
+  const { getChallenge, BotGuardClient } = bgGuard;
+  const { WebPoMinter } = bgWebPo;
+  const { buildURL, getHeaders } = bgUtils;
   const { JSDOM } = await import('jsdom');
 
   const dom = new JSDOM('<!DOCTYPE html><html lang="en"><body></body></html>', {
@@ -211,18 +219,18 @@ async function doMint(
 
   bridge();
   try {
-    const bgConfig: BgConfig = {
-      fetch: (input: unknown, init?: unknown) =>
+    // bgutils-js 4 replaced BG.Challenge.create(config) with a free getChallenge()
+    // whose config is narrower: no globalObj and no identifier (the content binding is
+    // supplied per-mint, which is what this module already did), and `fetch` renamed
+    // to `fetchFunction`.
+    const challenge = await getChallenge({
+      requestKey,
+      fetchFunction: ((input: unknown, init?: unknown) =>
         fetchImpl(input as Parameters<typeof fetch>[0], {
           ...(init as RequestInit | undefined),
           signal: (init as RequestInit | undefined)?.signal ?? opts.signal,
-        }),
-      globalObj: globalThis,
-      identifier: identifiers[0]!,
-      requestKey,
-    };
-
-    const challenge = await BG.Challenge.create(bgConfig);
+        })) as unknown as typeof fetch,
+    });
     if (!challenge) throw new Error('BotGuard challenge unavailable');
 
     const interpreter = challenge.interpreterJavascript?.privateDoNotAccessOrElseSafeScriptWrappedValue;
@@ -233,10 +241,16 @@ async function doMint(
     // PoToken generation; trust rests on that TLS connection.
     new Function(interpreter)();
 
-    const botguard = await BG.BotGuardClient.create({
+    if (!challenge.program || !challenge.globalName) {
+      throw new Error('BotGuard challenge missing program/globalName');
+    }
+    // `globalObj` was renamed `globalObject` in bgutils-js 4. Passing the old name
+    // leaves the VM without a global to attach to and the minter factory silently
+    // returns a non-function, so this rename is load-bearing, not cosmetic.
+    const botguard = await BotGuardClient.create({
       program: challenge.program,
       globalName: challenge.globalName,
-      globalObj: globalThis,
+      globalObject: globalThis,
     });
 
     const webPoSignalOutput: unknown[] = [];
@@ -260,7 +274,7 @@ async function doMint(
       throw new Error('Integrity token rejected by attestation server (likely a non-residential IP)');
     }
 
-    const minter = await BG.WebPoMinter.create({ integrityToken }, webPoSignalOutput);
+    const minter = await WebPoMinter.create({ integrityToken }, webPoSignalOutput);
 
     const tokens = new Map<string, string>();
     for (const id of identifiers) {
@@ -294,26 +308,27 @@ async function doMint(
 // Minimal structural types for the loosely-typed bgutils-js surface we touch.
 // ---------------------------------------------------------------------------
 
-interface BgConfig {
-  fetch: (input: unknown, init?: unknown) => Promise<Response>;
-  globalObj: unknown;
-  identifier: string;
-  requestKey: string;
+interface BgChallenge {
+  interpreterJavascript?: { privateDoNotAccessOrElseSafeScriptWrappedValue?: string };
+  program?: string;
+  globalName?: string;
 }
 
-interface BgNamespace {
-  Challenge: {
-    create(config: BgConfig): Promise<{
-      interpreterJavascript?: { privateDoNotAccessOrElseSafeScriptWrappedValue?: string };
-      program: string;
-      globalName: string;
-    } | undefined>;
-  };
+interface BgGuardModule {
+  getChallenge(config: {
+    requestKey: string;
+    fetchFunction: typeof fetch;
+    interpreterHash?: string;
+    useYouTubeAPI?: boolean;
+  }): Promise<BgChallenge | undefined>;
   BotGuardClient: {
-    create(opts: { program: string; globalName: string; globalObj: unknown }): Promise<{
+    create(opts: { program: string; globalName: string; globalObject: unknown }): Promise<{
       snapshot(args: { webPoSignalOutput: unknown[] }): Promise<string>;
     }>;
   };
+}
+
+interface BgWebPoModule {
   WebPoMinter: {
     create(
       integrity: { integrityToken: string },
@@ -322,9 +337,7 @@ interface BgNamespace {
   };
 }
 
-interface BgModule {
-  BG?: BgNamespace;
-  default: BgNamespace;
+interface BgUtilsModule {
   buildURL(endpoint: string, useYouTubeAPI?: boolean): string;
   getHeaders(): Record<string, string>;
 }