@lincoln504/pi-research 1.6.10 → 1.6.12

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

@@ -104,13 +104,15 @@ export class DeepResearchOrchestrator {
     const observer = this.observer;
     const container = tryGetServiceContainerFromCtx(ctx);
 
-    // RESEARCH_MODEL contract (config.ts): the coordinator and evaluator always
-    // use the caller's model (ctx.model); RESEARCH_MODEL overrides only the
-    // researcher sub-agents. `model` is the resolved research model — it equals
-    // ctx.model on the SDK/CLI path, but on the pi-tool path it is the
-    // RESEARCH_MODEL override, so planning must key off ctx.model explicitly.
-    // Fall back to `model` when the host exposes no ctx.model.
-    const coordinatorModel = (ctx.model as Model<any> | undefined) ?? model;
+    // The initial coordinator/evaluator (round 1 planning) uses the
+    // parent chat's model (ctx.model) so the prompt-cache prefix is
+    // shared with the conversation that preceded the research tool call —
+    // same provider, same model, same cache lineage.
+    // Later evaluator rounds (round 2+ routing) and final synthesis
+    // use the research model (RESEARCH_MODEL override or host model),
+    // which is also what the researcher sub-agents use.
+    const initialCoordinatorModel = (ctx.model as Model<any> | undefined) ?? model;
+    const evaluatorModel = model;
     
     const orchestrationService = await this.getOrchestrationService();
     const planningService = await this.getPlanningService();
@@ -249,7 +251,7 @@ export class DeepResearchOrchestrator {
                 sessionId: researchId,
                 query,
                 complexity,
-                model: coordinatorModel,
+                model: initialCoordinatorModel,
                 modelRegistry: ctx.modelRegistry,
                 cwd: ctx.cwd,
                 config: this.config,
@@ -274,7 +276,7 @@ export class DeepResearchOrchestrator {
                 query: query,
                 complexity,
                 round: this.currentRound,
-                model: coordinatorModel,
+                model: evaluatorModel,
                 modelRegistry: ctx.modelRegistry,
                 cwd: ctx.cwd,
                 config: this.config,
@@ -568,7 +570,7 @@ export class DeepResearchOrchestrator {
           query: query,
           complexity,
           round: this.currentRound,
-          model: coordinatorModel,
+          model: evaluatorModel,
           modelRegistry: ctx.modelRegistry,
           cwd: ctx.cwd,
           config: this.config,

package/src/sdk.ts

@@ -18,7 +18,8 @@ import {
   registerOrchestrationServices, 
   initializeOrchestrationServices 
 } from './orchestration/service-initialization.ts';
-import { getService, resetServiceContainer, getServiceContainer } from './core/service-registry.ts';
+import { getService, resetServiceContainer, getServiceContainer, tryGetService } from './core/service-registry.ts';
+import { raceWithDeadline } from './utils/safe-unref.ts';
 import type { ServiceContainer } from './core/service-registry.ts';
 import { ServiceNames } from './core/service-interfaces.ts';
 import type { IKnowledgeStoreService } from './core/interfaces/knowledge-interfaces.ts';
@@ -45,7 +46,7 @@ import { buildModelRegistry as sharedBuildModelRegistry, resolveModel } from './
 import { scrapeSingle } from './web-research/web-scraper.ts';
 import { validateInitialLinks } from './utils/url-utils.ts';
 import { validateUrlForSSRF, disposeSsrfSafeFetcher } from './web-research/scraper-utils.ts';
-import type { ScrapeResult } from './core/interfaces/scheduler-interfaces.ts';
+import type { ScrapeResult, ISchedulerService } from './core/interfaces/scheduler-interfaces.ts';
 import { randomUUID } from 'node:crypto';
 import type { ResearchDepth } from './types/index.ts';
 
@@ -278,11 +279,11 @@ async function _doInit(options: ResearchSDKOptions = {}): Promise<void> {
     globalApiKey = options.apiKey || process.env['PI_RESEARCH_API_KEY'];
     let parsedProvider = options.provider || process.env['PI_RESEARCH_PROVIDER'];
 
-    // An EXPLICIT model option must govern the entire run — coordinator (via
-    // ctx.model) AND researchers/synthesis (which resolve through
-    // RESEARCH_MODEL, where config would otherwise outrank the option and split
-    // the run across two models, with the report metadata naming the wrong one).
-    // Pin the config to the explicit choice. No-op when the option was itself
+    // An EXPLICIT model option must govern the entire run — the initial
+    // coordinator (via ctx.model, same provider as the parent chat for prompt
+    // cache continuity), the evaluator/synthesis rounds, and researchers/
+    // synthesis (which resolve through RESEARCH_MODEL). Pin the config to the
+    // explicit choice so the run is consistent. No-op when the option was itself
     // seeded from the config (the CLI does that).
     if (options.model) {
       const explicit = typeof options.model === 'string'
@@ -316,10 +317,12 @@ async function _doInit(options: ResearchSDKOptions = {}): Promise<void> {
     // Resolve the model. Precedence: explicit option (a Model object is used
     // as-is; it need not exist in the registry) → configured RESEARCH_MODEL →
     // provider default → registry fallback. Seeding the resolver with the
-    // configured model is what keeps the coordinator (which runs on ctx.model)
-    // on the SAME model as the researchers/synthesis (which read
-    // RESEARCH_MODEL themselves) — without it a configured model would govern
-    // only the sub-agents and planning would silently run on the fallback.
+    // configured model is what keeps the evaluator/synthesis rounds and
+    // researchers (which read RESEARCH_MODEL themselves) on the same model —
+    // without it a configured model would govern only the sub-agents and
+    // planning would silently run on the fallback. The initial coordinator
+    // (round 1) always uses ctx.model (the parent chat's model) for prompt-
+    // cache continuity, regardless of this seeding.
     if (effectiveModel && typeof effectiveModel === 'object' && (effectiveModel as any).id) {
       globalModel = effectiveModel as Model<any>;
     } else {
@@ -355,6 +358,30 @@ async function _doInit(options: ResearchSDKOptions = {}): Promise<void> {
     isInitialized = true;
     logger.log('[SDK] Research SDK initialized successfully');
 
+    // Stop the browser scheduler as the FIRST teardown step of a shutdown. This
+    // runs on EVERY teardown path — signal handlers (SIGINT/SIGTERM) and the
+    // cooperative shutdownResearchSDK() alike — which is intended: without it the
+    // sdk_shutdown cleanup list is empty ("No cleanup tasks registered"), and the scheduler's cluster workers died mid-DAG-disposal —
+    // with code null — while the worker pool was still live, which the pool's
+    // exitHandler counted as unexpected deaths ("3 consecutive exits → pool
+    // unhealthy") on a process that was exiting anyway. Shutting down here puts
+    // those deaths inside the pool's intentional-destroy window instead. Both
+    // teardown paths are idempotent (the later DAG dispose no-ops), and the task
+    // is bounded well inside the 15s signal force-exit deadline. Registered per
+    // init: runCleanup detaches the task set after running, so re-init gets a
+    // fresh registration.
+    shutdownManager.register(async () => {
+        if (!globalContainer) return;
+        const schedulerService = tryGetService<ISchedulerService>(ServiceNames.SCHEDULER, globalContainer);
+        const scheduler = schedulerService?.getScheduler?.();
+        if (!scheduler) return;
+        try {
+            await raceWithDeadline(scheduler.shutdown(), 12000);
+        } catch (err) {
+            logger.error('[SDK] Error stopping scheduler during shutdown cleanup:', err);
+        }
+    });
+
     // Register graceful-shutdown signal handlers (SIGINT/SIGTERM).
     // These are a safety net for scripts and long-running embedders —
     // the cooperative shutdownResearchSDK() API is still the primary path.

package/src/stackexchange/output/compact.ts

@@ -3,6 +3,7 @@
  */
 
 import type { Question, Answer, User, Site } from '../types.ts';
+import { plainUrl } from '../../utils/plain-url.ts';
 
 export function formatQuestionsCompact(questions: Question[]): string {
   if (questions.length === 0) {
@@ -13,7 +14,7 @@ export function formatQuestionsCompact(questions: Question[]): string {
   let index = 1;
   for (const q of questions) {
     const accepted = q.accepted_answer_id ? '[accepted]' : '         ';
-    lines.push(`${index}. ${accepted} [${q.title}](${q.link}) (${q.score} pts, ${q.answer_count} ans, ${q.view_count} views)`);
+    lines.push(`${index}. ${accepted} ${q.title} (${q.score} pts, ${q.answer_count} ans, ${q.view_count} views) ${plainUrl(q.link)}`);
     index++;
   }
   return lines.join('\n');

package/src/stackexchange/output/table.ts

@@ -3,6 +3,7 @@
  */
 
 import type { Question, Answer, User, Site } from '../types.ts';
+import { plainUrl, fenceBlock } from '../../utils/plain-url.ts';
 
 export function formatQuestionsTable(questions: Question[]): string {
   if (questions.length === 0) {
@@ -21,7 +22,10 @@ export function formatQuestionsTable(questions: Question[]): string {
     if (q.owner) {
       output += `- **Author:** ${q.owner.display_name} (rep: ${q.owner.reputation})\n`;
     }
-    output += `- **Link:** ${q.link}\n`;
+    // plainUrl: URLs in tool output are data, not interactive links — see
+    // plain-url.ts. Bare URLs would be GFM-autolinked into clickable OSC 8
+    // hyperlinks by markdown renderers (accidental browser-tab opens).
+    output += `- **Link:** ${plainUrl(q.link)}\n`;
     output += `- **Created:** ${new Date(q.creation_date * 1000).toLocaleString()}\n`;
 
     if (q.body) {
@@ -29,7 +33,13 @@ export function formatQuestionsTable(questions: Question[]): string {
       // previous `length < 1000` guard omitted the Body line for the longest
       // questions (the ones most in need of truncation).
       const body = q.body.length > 500 ? `${q.body.substring(0, 500)}...` : q.body;
-      output += `- **Body:** ${body}\n`;
+      // Third-party body text must never be rendered as markdown — it can
+      // carry arbitrary links (markdown injection → clickable browser tabs).
+      // The fence MUST start on its own line: CommonMark only recognizes a
+      // fenced code block when the opening fence begins the line; inline
+      // after "**Body:**" it degrades to paragraph text and marked renders
+      // embedded links clickable (verified against pi's bundled marked).
+      output += `- **Body:**\n\n${fenceBlock(body)}\n`;
     }
 
     output += '\n---\n\n';
@@ -62,7 +72,8 @@ export function formatAnswersTable(answers: Answer[]): string {
       // answers (same class as the question-body fix above; answers get a more
       // generous bound since the body is the whole point of an answer).
       const body = a.body.length > 2000 ? `${a.body.substring(0, 2000)}...` : a.body;
-      output += `\n### Answer Body\n\n${body}\n`;
+      // Same third-party-content rule as the question body above.
+      output += `\n### Answer Body\n\n${fenceBlock(body)}\n`;
     }
 
     output += '\n---\n\n';
@@ -89,9 +100,9 @@ export function formatUsersTable(users: User[]): string {
       output += `- **Location:** ${u.location}\n`;
     }
     if (u.website_url) {
-      output += `- **Website:** ${u.website_url}\n`;
+      output += `- **Website:** ${plainUrl(u.website_url)}\n`;
     }
-    output += `- **Profile:** ${u.link}\n`;
+    output += `- **Profile:** ${plainUrl(u.link)}\n`;
     output += '\n---\n\n';
   }
 
@@ -125,7 +136,7 @@ export function formatCompactQuestions(questions: Question[]): string {
   let index = 1;
   for (const q of questions) {
     const accepted = q.accepted_answer_id ? '[accepted]' : '';
-    output += `${index}. [${q.title}](${q.link}) ${accepted} (score: ${q.score}, answers: ${q.answer_count})\n`;
+    output += `${index}. ${q.title} ${accepted} (score: ${q.score}, answers: ${q.answer_count}) ${plainUrl(q.link)}\n`;
     index++;
   }
   return output;

package/src/tools/research-knowledge-search.ts

@@ -343,7 +343,7 @@ import { safeGetApiKeyAndHeaders } from '../core/llm/model-registry-factory.ts';
 
 /**
  * Resolve the model to use for the background synthesis LLM.
- * Priority: RESEARCH_MODEL → ctx.model
+ * Priority: explicit modelId → RESEARCH_MODEL → ctx.model → fallback
  */
 function resolveSynthesisModel(ctx: ExtensionContext, config: Config): { model?: Model<any>; error?: string } {
   try {

package/src/tools/stackexchange.ts

@@ -70,6 +70,7 @@ export function createStackexchangeTool(options: {
       'Use tags to filter by specific topics.',
       'Use maxPages parameter to control pagination for search results (default: 5 pages).',
       `CRITICAL: You are allowed a maximum of ${getMaxGatheringCalls(options.config)} gathering calls across your web tools (search, security_search, stackexchange). Use them for breadth.`,
+      'URLs in results are wrapped in backticks on purpose: they are data, not clickable links. Never reformat them as markdown links — a click in the terminal opens a real browser tab.',
     ],
     parameters: StackExchangeParamsSchema,
     executionMode: 'parallel',

package/src/tui/tui-controller.ts

@@ -8,7 +8,7 @@
  */
 
 import type { ExtensionUIContext } from '@earendil-works/pi-coding-agent';
-import { matchesKey } from '@earendil-works/pi-tui';
+import { isKeyRelease, matchesKey } from '@earendil-works/pi-tui';
 import { getActiveSessionCount, abortAllSessions, refreshAllSessions, hideMasterWidget } from '../orchestration/session-state.ts';
 import { logger } from '../logger.ts';
 
@@ -56,6 +56,26 @@ export function initGlobalTuiController(ui: ExtensionUIContext, piSessionId?: st
 
    */
   const handleTerminalInput = (data: string) => {
+    // Key-RELEASE events must be ignored. Pi runs the Kitty keyboard protocol
+    // with flag 2 (report event types), so every physical key sends TWO
+    // sequences: the press, then a release ~100-200ms later
+    // (e.g. ctrl+c press \x1b[99;5u, release \x1b[99;5:3u). Tui.handleTerminalInput
+    // filters releases — but ONLY for the focused component, AFTER extension
+    // input listeners run, and matchesKey cannot tell them apart
+    // (matchesKittySequence parses codepoint+modifier but never the event type,
+    // so a RELEASE matches matchesKey(data, 'ctrl+c') just like a press).
+    // Observed live 2026-09-03: one physical Ctrl+C with text in the editor
+    // logged "with editor text — clearing only" and then, 150ms later, the
+    // RELEASE event matched ctrl+c, saw the editor pi had just cleared, and
+    // aborted the research run. The same double-fire misclassified old
+    // ctrl+c releases as "Esc" aborts in the logs. pi's own components never
+    // see releases (tui filters them), so dropping them here matches pi's
+    // semantics exactly. Key REPEATS (\x1b[99;5:2u) are genuine held-key intent
+    // and keep flowing, like they do to pi's own components.
+    if (isKeyRelease(data)) {
+      return undefined;
+    }
+
     // If an interactive TUI is active (like the config menu), 
     // let it handle ALL input. We don't want to trigger a global abort
     // while the user is navigating a menu.
@@ -66,14 +86,25 @@ export function initGlobalTuiController(ui: ExtensionUIContext, piSessionId?: st
     // Check for specific global cancel keys (Escape and Ctrl+C)
     // We only trigger abort if research is actually running.
     if (matchesKey(data, 'escape') || matchesKey(data, 'ctrl+c')) {
-      // Ctrl+C is pi's app.clear ("Clear editor"), NOT its cancel key — pi's own
-      // handleCtrlC() clears the editor text and never interrupts the agent (Esc
-      // is app.interrupt). Aborting the run on every Ctrl+C stole the key from
-      // users who merely wanted to discard typed text mid-run. Follow pi's
-      // convention: with text in the editor, Ctrl+C only clears (fall through and
-      // let pi do the clearing); an EMPTY editor is an explicit cancel gesture and
-      // aborts the active research.
       if (matchesKey(data, 'ctrl+c')) {
+        // Ctrl+C is pi's app.clear ("Clear editor"), NOT its cancel key — Esc is
+        // app.interrupt. But pi's handleCtrlC() is TIME-based, not content-based:
+        // first press clears the editor and arms a window, and a SECOND press
+        // within 500ms calls shutdown() — exiting the entire pi process. There is
+        // no "abort research" step anywhere in it. Extension input listeners run
+        // BEFORE the focused editor and may consume keys, so this handler fully
+        // owns the Ctrl+C policy while a run is active:
+        //
+        //   editor has text  → fall through: pi clears the text, run continues
+        //                      (a follow-up press sees an empty editor → abort
+        //                      branch below — the two-step cancel the user asked
+        //                      for: clear first, second press aborts the run)
+        //   editor empty AND → abort the run AND CONSUME the key. Consuming is
+        //   run active         the fix: without it the abort fell through to pi's
+        //                      handleCtrlC, and a double-press within 500ms (the
+        //                      natural way to "abort now") shut down pi itself.
+        //   editor empty AND → fall through untouched: pi's native behavior
+        //   no run active      (clear/arm, double-press exit) must keep working.
         let editorText = '';
         try {
           editorText = typeof ui.getEditorText === 'function' ? (ui.getEditorText() ?? '') : '';
@@ -82,13 +113,27 @@ export function initGlobalTuiController(ui: ExtensionUIContext, piSessionId?: st
           logger.debug('[TUI] Ctrl+C with editor text — clearing only, research keeps running.');
           return undefined;
         }
+        const activeCount = getActiveSessionCount();
+        if (activeCount > 0) {
+          logger.info('[TUI] Ctrl+C with empty editor — aborting active research (key consumed so pi\'s double-press exit cannot fire).');
+          try {
+            // Scope to this Pi session to avoid cross-session interference
+            abortAllSessions(state.piSessionId);
+          } catch (err) {
+            logger.error('[TUI] Failed to abort sessions on Ctrl+C:', err);
+          }
+          return { consume: true };
+        }
+        // No research running — native pi Ctrl+C (clear editor / double-press exit).
+        return undefined;
       }
+
+      // Esc (pi's app.interrupt): panic-cancel regardless of editor text. Abort the
+      // active run, then let the key fall through so Pi can also respond
+      // (cancelling its own agent loop) and other TUIs can react.
       const activeCount = getActiveSessionCount();
       if (activeCount > 0) {
-        // FIX (New Issues B & E): Use abortAllSessions scoped to the current Pi session
-        // instead of clearAllSessionState() which nukes ALL sessions across ALL Pi instances.
-        logger.info(`[TUI] Global cancel requested (${data === '\x03' ? 'Ctrl+C' : 'Esc'}). Aborting active sessions...`);
-        
+        logger.info('[TUI] Global cancel requested (Esc). Aborting active sessions...');
         try {
           // Scope to this Pi session to avoid cross-session interference
           abortAllSessions(state.piSessionId);
@@ -96,9 +141,6 @@ export function initGlobalTuiController(ui: ExtensionUIContext, piSessionId?: st
           logger.error('[TUI] Failed to abort sessions on cancel:', err);
         }
       }
-      
-      // Let the key fall through so Pi can handle its own cancellation
-      // or other TUIs can respond.
       return undefined;
     }
 

package/src/utils/plain-url.ts

@@ -0,0 +1,44 @@
+/**
+ * Neutralize external URLs in tool output so terminal-UI markdown renderers
+ * cannot turn them into clickable hyperlinks.
+ *
+ * Why this exists: pi's TUI (and most markdown-rendering terminals) convert
+ * markdown links AND bare URLs (GFM autolink) into OSC 8 terminal hyperlinks,
+ * and a mouse press+release on such a span opens the URL in the user's real
+ * browser. Tool results are agent-facing data, not interactive UI — a URL
+ * appearing there should never be one accidental click away from opening a
+ * tab, and third-party content (question bodies, API fields) must not be able
+ * to inject clickable links into the user's terminal at all.
+ *
+ * Mechanism: wrapping a URL in backticks makes it a markdown code span. Code
+ * spans are tokenized before autolink in every CommonMark/GFM tokenizer
+ * (verified against the `marked` version pi ships), so the URL renders as
+ * literal text — copyable by humans, trivially extractable by the model, and
+ * impossible to click.
+ */
+
+/** Longest run of backticks that can safely fence arbitrary content. */
+const MIN_FENCE = 3;
+
+/**
+ * Return `url` as a markdown code span: renders as plain text everywhere,
+ * never becomes a clickable hyperlink, and stays byte-exact for the model.
+ */
+export function plainUrl(url: string): string {
+  const safe = url.replace(/`/g, '%60');
+  return `\`${safe}\``;
+}
+
+/**
+ * Wrap arbitrary third-party text (question bodies, API-provided markup) in a
+ * fenced code block so no markdown inside it — links, headings, tables — is
+ * ever rendered or autolinked. The fence length grows past any backtick run
+ * found in the content, so content containing ``` fences cannot close it
+ * early.
+ */
+export function fenceBlock(content: string): string {
+  const runs = content.match(/`+/g) ?? [];
+  const longest = runs.reduce((max, run) => Math.max(max, run.length), 0);
+  const fence = '`'.repeat(Math.max(MIN_FENCE, longest + 1));
+  return `${fence}text\n${content}\n${fence}`;
+}

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

@@ -205,11 +205,21 @@ function messageIsTransient(message: string): boolean {
   // here on purpose — the generic classifier keeps "timeout"/"etimedout"; the LLM
   // wrapper's "cancelled or timed out" wording is handled by the planning-service
   // classifier, so a security/youtube caller's abort string isn't reinterpreted.
+  //
+  // "connection error" is the OpenAI SDK's APIConnectionError default message (the
+  // shape pi-ai surfaces for openai-completions providers like OpenRouter when the
+  // fetch itself fails before any response — refused / reset / DNS / TLS). The SDK
+  // only throws this class for fetch-level transport failures (its own 2 internal
+  // retries already exhausted), so the string is a reliable transient signal. Seen
+  // live 2026-09-02: OpenRouter planning call died in 4s with zero retries because
+  // this pattern was missing — and the same miss made isDegradableLlmError throw
+  // instead of degrading to the fallback plan. Both layers gate on this matcher.
   if (
     m.includes('econnrefused') || m.includes('enotfound') || m.includes('timeout') ||
     m.includes('etimedout') || m.includes('econnreset') || m.includes('fetch failed') ||
     m.includes('terminated') || m.includes('other side closed') ||
-    m.includes('socket hang up') || m.includes('und_err')
+    m.includes('socket hang up') || m.includes('und_err') ||
+    m.includes('connection error')
   ) {
     return true;
   }