@lincoln504/pi-research 1.6.9 → 1.6.11

package/src/research-config.ts

@@ -89,12 +89,34 @@ const ENV_KEY_BY_SETTING_ID: Record<string, string> = {
  * Main command handler for /research-config
  */
 export async function handleResearchConfigCommand(
-  _args: string,
+  args: string,
   ctx: ExtensionContext,
   pi: ExtensionAPI
 ): Promise<void> {
-  if (!ctx.hasUI) {
-    ctx.ui.notify('Interactive menu requires UI mode', 'error');
+  const verb = args.trim().split(/\s+/)[0]?.toLowerCase() ?? '';
+  if (verb === 'health') {
+    await runHealthCheckAction(ctx, pi);
+    return;
+  }
+  if (verb === 'knowledge-status' || verb === 'knowledge_status') {
+    await showKnowledgeStatusAction(ctx, pi);
+    return;
+  }
+  if (ctx.mode !== 'tui' || !ctx.hasUI) {
+    // The interactive menu needs pi's real TUI. In RPC/web-hub/print/json/SDK hosts
+    // ctx.hasUI is true (RPC) and the menu cannot render — awaiting it silently
+    // nudges the host toward a hang and at best does nothing visible. Give a clear
+    // non-interactive answer with the headless diagnostics that DO work here.
+    pi.sendMessage({
+      customType: 'research-config',
+      content: 'The interactive `/research-config` menu requires pi\'s terminal UI (TUI).\n\n' +
+        'In this host, use the headless diagnostics instead:\n' +
+        '- `/research-config health` — system health status\n' +
+        '- `/research-config knowledge-status` — knowledge store status\n\n' +
+        'Configuration is read from the environment and config files; set `PI_RESEARCH_*` ' +
+        'environment variables to change it.',
+      display: true,
+    });
     return;
   }
   await showInteractiveMenu(ctx, pi);
@@ -498,6 +520,7 @@ async function showInteractiveMenu(ctx: ExtensionContext, pi: ExtensionAPI): Pro
         modelChangeConfirmed = !cancelled && await ctx.ui.confirm(
           'Change Embedding Model',
           `Switch the embedding model to ${config.EMBEDDING_MODEL.split('/').pop()}? This permanently clears the current knowledge store.`,
+          { timeout: 60_000 },
         );
         if (modelChangeConfirmed) {
           logger.info(`[research-config] Embedding model changed from ${initialConfig.EMBEDDING_MODEL} to ${config.EMBEDDING_MODEL}. Clearing knowledge store.`);
@@ -550,7 +573,7 @@ async function showInteractiveMenu(ctx: ExtensionContext, pi: ExtensionAPI): Pro
             await showKnowledgeStatusAction(ctx, pi);
             break;
           case 'knowledge_clear_global': {
-            const confirmed = await ctx.ui.confirm('Clear User Store', 'Permanently delete all user-scoped store data?');
+            const confirmed = await ctx.ui.confirm('Clear User Store', 'Permanently delete all user-scoped store data?', { timeout: 60_000 });
             if (confirmed) {
               try {
                 const service = await getService<IKnowledgeStoreService>(ServiceNames.KNOWLEDGE_STORE, ctx, container);
@@ -563,7 +586,7 @@ async function showInteractiveMenu(ctx: ExtensionContext, pi: ExtensionAPI): Pro
             break;
           }
           case 'knowledge_clear_local': {
-            const confirmed = await ctx.ui.confirm('Clear Project Store', 'Permanently delete all project-scoped store data?');
+            const confirmed = await ctx.ui.confirm('Clear Project Store', 'Permanently delete all project-scoped store data?', { timeout: 60_000 });
             if (confirmed) {
               try {
                 const service = await getService<IKnowledgeStoreService>(ServiceNames.KNOWLEDGE_STORE, ctx, container);
@@ -577,13 +600,13 @@ async function showInteractiveMenu(ctx: ExtensionContext, pi: ExtensionAPI): Pro
           }
           case 'metrics':
             await showMetricsAction(ctx, pi);
-            if (await ctx.ui.confirm('Session Metrics', 'Reset all session counters?')) {
+            if (await ctx.ui.confirm('Session Metrics', 'Reset all session counters?', { timeout: 60_000 })) {
               metrics.clearSession();
               ctx.ui.notify('Session metrics reset.', 'info');
             }
             break;
           case 'logs_clear': {
-            const confirmed = await ctx.ui.confirm('Clear Logs', 'Delete the main diagnostic log file and all archived rotation files?');
+            const confirmed = await ctx.ui.confirm('Clear Logs', 'Delete the main diagnostic log file and all archived rotation files?', { timeout: 60_000 });
             if (confirmed) {
               logger.clear();
               ctx.ui.notify('Diagnostic logs cleared.', 'info');
@@ -704,6 +727,7 @@ async function uninstallSkillAction(ctx: ExtensionContext, pi: ExtensionAPI): Pr
   const confirmed = await ctx.ui.confirm(
     'Uninstall Skill',
     `Remove the pi-research skill from ${names}? (Only symlinks this extension created are removed.)`,
+    { timeout: 60_000 },
   );
   if (!confirmed) return;
   try {

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/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/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,12 +86,54 @@ 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')) {
+      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() ?? '') : '';
+        } catch { /* editor gone mid-run — treat as empty (cancel) */ }
+        if (editorText.length > 0) {
+          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);
@@ -79,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/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;
   }