@lincoln504/pi-research 1.3.12 → 1.4.3

package/src/config.ts

@@ -82,13 +82,19 @@ export const ConfigSchema = Type.Object({
   SEARCH_TIMEOUT_MS: Type.Number({ minimum: 5000, maximum: 120000, default: 45000 }),
   /** TUI refresh debounce in milliseconds (default: 100ms) */
   TUI_REFRESH_DEBOUNCE_MS: Type.Number({ minimum: 0, maximum: 1000, default: 100 }),
-  /** Queue-wait / overhead margin (ms) added on top of each browser operation's own nav
-   *  timeout to form its scheduler task-timeout ceiling: a search task times out after
-   *  SEARCH_TIMEOUT_MS + this, a scrape after SCRAPE_TIMEOUT_MS + this. Sized so a task is
-   *  never killed before it has used its full nav budget plus time waiting in the queue.
+  /** Overhead margin (ms) added on top of each browser operation's own nav timeout to
+   *  form its scheduler task-timeout ceiling: a search task times out after
+   *  SEARCH_TIMEOUT_MS + this, a scrape after SCRAPE_TIMEOUT_MS + this — covering
+   *  per-task work beyond raw navigation (page setup, result parsing). Queue wait is
+   *  NOT part of this margin: the deadline is armed on dispatch, not on enqueue, so
+   *  time spent waiting for a free worker never counts against it (see
+   *  browser-task-scheduler.ts). Cold browser-launch/context-creation time is also
+   *  separate from this margin — COLD_START_ALLOWANCE_MS
+   *  (infrastructure/browser/config.ts) covers that unconditionally on top of it,
+   *  since it isn't something a user should need to tune.
    *  (default: 10000) */
   BROWSER_TASK_TIMEOUT_MS: Type.Number({ minimum: 2000, maximum: 120000, default: 10000 }),
-  /** Timeout for coordinator/evaluator/repair/knowledge LLM calls in ms (default: 300000 = 5 min, range: 60s-30min).
+  /** Timeout for coordinator/research-lead/repair/knowledge LLM calls in ms (default: 300000 = 5 min, range: 60s-30min).
    *  Not exposed in TUI — controlled via PI_RESEARCH_LLM_TIMEOUT_MS env var.
    *  Ceiling raised to 30min (matching RESEARCHER_TIMEOUT_MS): a slow model on a
    *  large-context synthesis/plan call can legitimately run >10min, and the old
@@ -96,7 +102,7 @@ export const ConfigSchema = Type.Object({
    *  (e.g. 900000), causing those calls to time out mid-generation. */
   LLM_TIMEOUT_MS: Type.Number({ minimum: 60000, maximum: 1800000, default: 300000 }),
   /** Chain-of-thought "thinking" level for the engine's own LLM calls (coordinator,
-   *  evaluator, synthesis, JSON-repair, knowledge extraction) AND the researcher
+   *  router, synthesizer, JSON-repair, knowledge extraction) AND the researcher
    *  sub-agents. Default 'off': these calls emit structured JSON / cited reports, not
    *  open-ended reasoning, so thinking only burns the output-token budget (often
    *  truncating before the JSON/report block) and adds latency for at most a marginal
@@ -111,22 +117,26 @@ export const ConfigSchema = Type.Object({
     Type.Literal('medium'),
     Type.Literal('high'),
   ], { default: 'off' }),
-  /** Max output tokens for the coordinator plan + mid-round evaluator decision (and,
-   *  when the evaluator synthesizes mid-round, the report). Default 16384. The blanket
+  /** Max output tokens for the coordinator's round-1 plan. Default 16384. The routing
+   *  decision has its OWN, much smaller ceiling (it emits a decision, never a report,
+   *  and cannot synthesize mid-round under the split protocol); the final report uses
+   *  SYNTHESIS_MAX_TOKENS below. The blanket
    *  4096 cap previously throttled every call and could be exhausted by a thinking block
    *  before any text was emitted. Capped at the model's real ceiling at call time.
    *  Not exposed in TUI — controlled via PI_RESEARCH_PLANNING_MAX_TOKENS env var. */
   PLANNING_MAX_TOKENS: Type.Number({ minimum: 1024, maximum: 131072, default: 16384 }),
-  /** Max output tokens for the final synthesized research report (the forced-synthesis
-   *  evaluator call). Default 32768 so a full cited report is never truncated. Capped at
+  /** Max output tokens for the final synthesized research report (the synthesizer call,
+   *  and each pass of a reduce when the corpus does not fit in one). Default 32768 so a
+   *  full cited report is never truncated. It is also the reserve subtracted from the
+   *  model's context window when budgeting that corpus. Capped at
    *  the model's real maxTokens at call time.
    *  Not exposed in TUI — controlled via PI_RESEARCH_SYNTHESIS_MAX_TOKENS env var. */
   SYNTHESIS_MAX_TOKENS: Type.Number({ minimum: 1024, maximum: 131072, default: 32768 }),
   /** LLM Model override for researcher sub-agents and knowledge synthesis.
    *  Format: provider/model-id (e.g. google/gemini-2.0-flash-001) or just model-id.
    *  When set, this overrides ctx.model for researcher sub-agents (both deep and quick)
-   *  and the knowledge synthesis background LLM. The coordinator and evaluator always
-   *  use the caller's model (ctx.model).
+   *  and the knowledge synthesis background LLM. The coordinator and the research lead
+   *  always use the caller's model (ctx.model).
    */
   RESEARCH_MODEL: Type.Optional(Type.String()),
   /** Explicit directory for the knowledge store database (overrides default) */

package/src/constants.ts

@@ -69,7 +69,7 @@ export function getUnitsPerResearcher(config?: Config): number {
   return 1 + Math.min(batches, 4);
 }
 
-/** Progress bar weight per lead evaluator round */
+/** Progress bar weight per research-lead round */
 export const LEAD_EVAL_UNITS = 2;
 
 

package/src/core/interfaces/observer-interfaces.ts

@@ -58,9 +58,9 @@ export interface ResearchObserver {
   // Synthesis/Completion
   /**
    * Fired when the run enters FINAL synthesis / stops consuming steering:
-   *   - deep mode: right before the forced (mustSynthesize) evaluator call, and
-   *     on the evaluator-chose-synthesize path (idempotent there — the flag is
-   *     already off via onEvaluationDecision('synthesize')).
+   *   - deep mode: right before the synthesizer call, and on the path where the
+   *     router chose to finish early (idempotent there — the flag is already off
+   *     via onEvaluationDecision('synthesize')).
    *   - quick mode: as soon as the researcher session settles, i.e. the point
    *     the 500ms steering-consume poller stops running.
    * TUI consequence: steeringAcceptable flips false, so a late steer takes the

package/src/core/interfaces/orchestration-interfaces.ts

@@ -59,6 +59,8 @@ export interface RunResearchersOptions {
 export interface IResearchSynthesisService extends IService {
   storeReport(researchId: string, researcherId: string, report: string): void;
   getAllReports(researchId: string): Map<string, string>;
+  /** Coverage digest per stored report, derived when a researcher emitted none. */
+  getAllDigests(researchId: string): Map<string, string>;
   getReport(researchId: string, id: string): string | undefined;
   getReportsForRound(researchId: string, round: number): Map<string, string>;
   getReportCount(researchId: string): number;

package/src/core/interfaces/planning-interfaces.ts

@@ -56,6 +56,12 @@ export interface GenerateQueriesOptions {
 export interface UpdatePlanOptions {
   sessionId: string;
   reports: Map<string, string>;
+  /** Coverage digest per report id. The router reads the FRESH round's reports in full
+   *  (evidence-based routing) and falls back to these digests only for PRIOR rounds — it
+   *  does not read digests instead of the current round's reports. Optional: when omitted,
+   *  digests are derived from the report bodies so a caller that doesn't track them still
+   *  routes on coverage rather than on nothing. */
+  digests?: Map<string, string>;
   round: number;
   query: string;
   complexity: 1 | 2 | 3;
@@ -98,7 +104,7 @@ export interface IPlanningService extends IService {
   getTeamSize(complexity: 1 | 2 | 3): number;
   getQueryBudget(complexity: 1 | 2 | 3): number;
   getComplexityGuidance(complexity: 1 | 2 | 3, maxTeamSize: number, queryBudget: number): string;
-  getEvaluatorComplexityGuidance(complexity: 1 | 2 | 3): string;
+  getEvaluatorComplexityGuidance(complexity: 1 | 2 | 3, researchRounds: number): string;
   getRoundPhaseGuidance(currentRound: number, maxRounds: number, complexity: 1 | 2 | 3, maxTeamSize: number): string;
   capResearcherQueries(plan: ResearchPlan, complexity: 1 | 2 | 3, serviceName: string): ResearchPlan;
   parseJsonPlan(text: string): ResearchPlan;

package/src/core/interfaces/scheduler-interfaces.ts

@@ -70,9 +70,25 @@ export interface ScrapeResult {
 /**
  * Base scheduler interface
  */
+/**
+ * Reports when a task's EXECUTION starts and stops.
+ *
+ * Callers that keep their own guard over a scheduler call arm it on 'dispatched'
+ * rather than at call time, so queue wait never counts against the work's budget,
+ * and disarm it on 'settled' so the guard is not left running over a period in
+ * which nothing is executing — between a failed attempt and its retry, that
+ * period includes a backoff sleep, a re-enqueue and a fresh queue wait, and a
+ * timer left armed across it kills the retry for the predecessor's overrun.
+ *
+ * An implementation that cannot observe dispatch (BrowserClient, which only sees
+ * the leader's final reply) never calls it at all, and the caller's guard stays
+ * disarmed — that implementation bounds the call itself.
+ */
+export type TaskDispatchListener = (event: 'dispatched' | 'settled') => void;
+
 export interface IScheduler {
-  runSearch(query: string, config?: Config, signal?: AbortSignal): Promise<SearchResult[]>;
-  runScrape(url: string, config?: Config, signal?: AbortSignal): Promise<ScrapeResult>;
+  runSearch(query: string, config?: Config, signal?: AbortSignal, onTaskEvent?: TaskDispatchListener): Promise<SearchResult[]>;
+  runScrape(url: string, config?: Config, signal?: AbortSignal, onTaskEvent?: TaskDispatchListener): Promise<ScrapeResult>;
   runHealthCheck(config?: Config, signal?: AbortSignal): Promise<{ success: boolean }>;
   shutdown(): Promise<void>;
   resetIdleTimerOnActivity?(): void;

package/src/core/llm/agentic-repair.ts

@@ -34,6 +34,10 @@ export interface JsonRepairOptions {
   maxTokens?: number;
   /** Thinking level for the repair pass (default 'off' — repair emits JSON, not reasoning). */
   thinkingLevel?: ModelThinkingLevel;
+  /** Research session id, forwarded to the provider as its prompt-cache / session-affinity
+   *  key (see llm-utils.buildSafeOptions). Keeps the repair pass on the same upstream
+   *  replica as the call it is repairing. */
+  sessionId?: string;
   /** Usage sink invoked once per billed LLM attempt with the raw usage object from
    *  the response. Lets callers attribute the repair pass's tokens/cost to the run
    *  (metrics + observer) exactly as they do for the primary call. Every attempt that
@@ -70,7 +74,7 @@ export async function repairJsonWithLlm<T = any>(
   auth: { apiKey: string; headers?: Record<string, string | null> },
   options: JsonRepairOptions
 ): Promise<T | null> {
-  const { model, context, schema, serviceName = 'RepairService', signal, maxTokens = 16384, thinkingLevel = 'off' } = options;
+  const { model, context, schema, serviceName = 'RepairService', signal, maxTokens = 16384, thinkingLevel = 'off', sessionId } = options;
   
   logger.warn(`[${serviceName}] JSON parse failed; attempting agentic salvage`);
 
@@ -118,7 +122,8 @@ Return ONLY the valid JSON object. No prose before or after.`;
           ],
         }, buildSafeOptions(model, {
           ...auth,
-          signal
+          signal,
+          ...(sessionId ? { sessionId } : {}),
         }, maxTokens, thinkingLevel)),
         llmTimeout, `agentic-repair-${serviceName}`,
       );

package/src/core/llm/inject-date.ts

@@ -35,7 +35,10 @@ function getCurrentDateString(): string {
  * training-cutoff defaults). The full date follows for precision. Applies to
  * coordinator, researcher, and evaluator across all modes.
  */
-export function injectCurrentDate(prompt: string, _agentType: 'coordinator' | 'researcher' | 'evaluator'): string {
+export function injectCurrentDate(
+  prompt: string,
+  _agentType: 'coordinator' | 'researcher' | 'router' | 'synthesizer',
+): string {
   const monthYear = getCurrentMonthYearString();
   const fullDate = getCurrentDateString();
   // Derive the stale-year examples from the current year so the guidance stays correct in any

package/src/core/llm/llm-utils.ts

@@ -22,6 +22,13 @@ import { logger } from '../../logger.ts';
  *   thinking block only consumes the output-token budget (often truncating before the
  *   text block is emitted) for at most a marginal quality gain that does not justify the cost.
  *
+ * Callers should also pass the research `sessionId` in `options`. pi-ai forwards it as the
+ * provider's prompt-cache / session-affinity key — OpenAI's `prompt_cache_key`, OpenRouter's
+ * `x-session-id` — which keeps a run's calls on the replica that warmed their cache. Without
+ * it OpenRouter falls back to hashing the first system and user messages, which every round
+ * of a research run mutates, so it re-routes and re-warms. Providers that do not implement
+ * session affinity ignore the field, so passing it is unconditionally safe.
+ *
  * @param model - The model being called
  * @param options - Caller-provided options (an explicit `reasoning` here wins)
  * @param defaultCap - Default maxTokens cap (clamped to model.maxTokens)