@lincoln504/pi-research 1.0.3 → 1.0.4

package/dist/cli.mjs

@@ -3252,7 +3252,7 @@ function buildModelRegistry(apiKey, provider) {
       fs5.existsSync(modelsJsonPath) ? modelsJsonPath : void 0
     );
   }
-  if (fs5.existsSync(authPath)) {
+  if (fs5.existsSync(authPath) || fs5.existsSync(modelsJsonPath)) {
     const authStorage = AuthStorage.create(authPath);
     return ModelRegistry.create(
       authStorage,
@@ -3266,7 +3266,17 @@ function constructMinimalModel(provider, modelId, _apiKey) {
     provider,
     id: modelId,
     name: modelId,
-    api: provider === "openai" ? "openai-completions" : provider + "-conversations",
+    // Map to a REAL pi-ai api id — "<provider>-conversations" is not one, and a
+    // keyed no-registry setup would pass pre-flight then die on the first call.
+    // Unknown providers default to the OpenAI-compatible protocol, which is what
+    // virtually every third-party endpoint (openrouter, groq, cerebras, …) speaks.
+    api: {
+      openai: "openai-completions",
+      anthropic: "anthropic-messages",
+      google: "google-generative-ai",
+      gemini: "google-generative-ai",
+      mistral: "mistral-conversations"
+    }[provider] ?? "openai-completions",
     baseUrl: "",
     // Provider-specific base URLs are handled by pi-ai internal registry
     reasoning: false,
@@ -19812,6 +19822,7 @@ function getPiState(piSessionId) {
   if (!state) {
     state = {
       failures: /* @__PURE__ */ new Map(),
+      failureReasons: /* @__PURE__ */ new Map(),
       order: [],
       panels: /* @__PURE__ */ new Map(),
       aborts: /* @__PURE__ */ new Map(),
@@ -19883,6 +19894,7 @@ function refreshAllSessions(piSessionId) {
         for (const id of state.order) {
           if (!validIds.includes(id)) {
             state.failures.delete(id);
+            state.failureReasons.delete(id);
             state.panels.delete(id);
           }
         }
@@ -19914,6 +19926,7 @@ function endResearchSession(piSessionId, researchId) {
   const state = piSessions.get(sid);
   if (!state) return;
   state.failures.delete(researchId);
+  state.failureReasons.delete(researchId);
   state.panels.delete(researchId);
   state.aborts.delete(researchId);
   const index = state.order.indexOf(researchId);
@@ -19931,6 +19944,7 @@ function endResearchSession(piSessionId, researchId) {
       piSessions.delete(sid);
     } else {
       state.failures.clear();
+      state.failureReasons.clear();
       state.aborts.clear();
     }
   }
@@ -19952,12 +19966,23 @@ function clearAllSessionState() {
   clearAllSharedLinks();
   logger.log("[session-state] All session state cleared");
 }
-function recordResearcherFailure(piSessionId, researchId, researcherId) {
+function recordResearcherFailure(piSessionId, researchId, researcherId, reason) {
   const sid = normalizeSessionId(piSessionId);
   const state = getPiState(sid);
   const failures = state.failures.get(researchId) || [];
   failures.push(researcherId);
   state.failures.set(researchId, failures);
+  if (reason) {
+    const reasons = state.failureReasons.get(researchId) ?? /* @__PURE__ */ new Map();
+    if (!reasons.has(researcherId)) reasons.set(researcherId, reason);
+    state.failureReasons.set(researchId, reasons);
+  }
+}
+function getResearcherFailureReasons(piSessionId, researchId) {
+  const sid = normalizeSessionId(piSessionId);
+  const state = getPiState(sid);
+  const reasons = state.failureReasons.get(researchId);
+  return reasons ? Object.fromEntries(reasons) : {};
 }
 function getFailedResearchers(piSessionId, researchId) {
   const sid = normalizeSessionId(piSessionId);
@@ -19974,9 +19999,13 @@ function getResearchStopMessage(piSessionId, researchId) {
   const sid = normalizeSessionId(piSessionId);
   const failed = getFailedResearchers(sid, researchId);
   const count = failed.length;
+  const state = getPiState(sid);
+  const reasons = state.failureReasons.get(researchId);
+  const recorded = reasons && reasons.size > 0 ? ["Recorded errors:", ...[...reasons].map(([id, r]) => `\u2022 researcher ${id}: ${r}`), ""] : [];
   return [
     `Research stopped: ${count} researcher(s) did not return a usable report: ${failed.join(", ")}.`,
     "",
+    ...recorded,
     "Most likely cause \u2014 the research model could not produce grounded results:",
     '\u2022 Try a more capable research model. Very small or "thinking-only" models often',
     "  emit no final text after their tool calls, which fails every researcher.",
@@ -20026,7 +20055,7 @@ ${currentPlan.allQueries.map((q) => `- ${q}`).join("\n")}
   const researcherPromptTemplate = loadPrompt("researcher");
   if (initialLinks.length === 0 && historicalUrls.length === 0) {
     logger.warn(`[ResearcherExecutor] Researcher ${id} has no initial search results or historical links; skipping.`);
-    recordResearcherFailure(sessionId, researchId, id);
+    recordResearcherFailure(sessionId, researchId, id, "no initial search results or historical links (search produced nothing usable)");
     metrics.increment("researcher_skipped_total", 1, { mode: "deep", complexity: String(complexity), reason: "no_initial_links" });
     observer?.onResearcherFailure?.(id, "No initial search results or historical links available");
     return;
@@ -20966,7 +20995,12 @@ var DeepResearchOrchestrator = class {
           logger.warn(`[DeepOrchestrator] LLM returned empty synthesis for ${researchId}, building fallback from ${synthesisService2.getReportCount(researchId)} reports`);
           result = synthesisService2.buildFallbackSynthesis(researchId, this.currentRound);
         } else {
-          result = "Research completed but no summary was generated.";
+          const failedIds = getFailedResearchers(this.options.sessionId, researchId);
+          const reasons = getResearcherFailureReasons(this.options.sessionId, researchId);
+          const causes = failedIds.map((id) => `researcher ${id}: ${reasons[id] ?? "no usable report"}`).join("; ");
+          throw new Error(
+            "Research produced no report \u2014 no source material was collected" + (causes ? `. Causes: ${causes}` : ".")
+          );
         }
       }
       try {
@@ -21268,7 +21302,7 @@ var ResearchOrchestrationService = class {
             logger.debug(`[ResearchOrchestrationService] Researcher ${id} cancelled (aborted).`);
           } else {
             logger.error(`[ResearchOrchestrationService] Researcher ${id} failed: ${errMsg}`);
-            recordResearcherFailure(sessionId, researchId, id);
+            recordResearcherFailure(sessionId, researchId, id, errMsg);
             observer?.onResearcherFailure?.(id, errMsg);
           }
         }
@@ -22000,6 +22034,10 @@ async function _doInit(options = {}) {
   }
   globalApiKey = options.apiKey || process.env["PI_RESEARCH_API_KEY"];
   let parsedProvider = options.provider || process.env["PI_RESEARCH_PROVIDER"];
+  if (options.model) {
+    const explicit = typeof options.model === "string" ? options.model : `${options.model.provider}/${options.model.id}`;
+    globalConfig = { ...globalConfig, RESEARCH_MODEL: explicit };
+  }
   const effectiveModel = options.model ?? globalConfig.RESEARCH_MODEL;
   if (!parsedProvider && effectiveModel) {
     if (typeof effectiveModel === "string") {
@@ -22475,6 +22513,7 @@ Total cost: ${costStr}`;
 
 // src/cli.ts
 init_config();
+init_model_registry_factory();
 import { getAgentDir as getAgentDir2 } from "@earendil-works/pi-coding-agent";
 function readPkgVersion() {
   try {
@@ -22593,6 +22632,15 @@ function fileExists(p) {
     return false;
   }
 }
+function piKeysAvailable(piAuthPresent, provider) {
+  try {
+    const available = safeGetAvailable(buildModelRegistry(void 0, void 0));
+    if (!provider) return available.length > 0;
+    return available.some((m) => m.provider === provider);
+  } catch {
+    return piAuthPresent;
+  }
+}
 function detectCredentials() {
   const paths = resolvedConfigPaths();
   const piAuthPresent = fileExists(paths.piAuth);
@@ -22604,6 +22652,7 @@ function detectCredentials() {
   const model = modelEnv ?? modelConfig;
   const modelFrom = modelEnv ? "PI_RESEARCH_MODEL" : modelConfig ? "config.env" : "unset";
   const provider = providerEnv ?? (model && model.includes("/") ? model.slice(0, model.indexOf("/")) : void 0);
+  const piKeysUsable = piKeysAvailable(piAuthPresent, provider);
   if (apiKey) {
     if (!provider) {
       return {
@@ -22639,7 +22688,7 @@ function detectCredentials() {
       piModelsPresent
     };
   }
-  if (piAuthPresent) {
+  if (piKeysUsable) {
     if (!model) {
       return {
         source: "pi-config",
@@ -22649,13 +22698,13 @@ function detectCredentials() {
         modelFrom,
         piAuthPresent,
         piModelsPresent,
-        problem: 'pi credentials were found (auth.json), but no research model is configured. The standalone CLI / agent skill run only on an explicitly configured model \u2014 they do not follow the model selected inside the pi extension. Set PI_RESEARCH_MODEL to a "provider/model-id" (in the environment, or in config.env / cli.env below).'
+        problem: `pi credentials were found (in pi's configuration), but no research model is configured. The standalone CLI / agent skill run only on an explicitly configured model \u2014 they do not follow the model selected inside the pi extension. Set PI_RESEARCH_MODEL to a "provider/model-id" (in the environment, or in config.env / cli.env below).`
       };
     }
     return {
       source: "pi-config",
       apiKeyConfigured: true,
-      // key lives in auth.json; SDK reads it
+      // key lives in pi's configuration; the SDK reads it at call time
       provider,
       model,
       modelFrom,
@@ -22671,7 +22720,7 @@ function detectCredentials() {
     modelFrom,
     piAuthPresent,
     piModelsPresent,
-    problem: "No model or API key is configured for pi-research. Provide credentials via environment variables (PI_RESEARCH_API_KEY + PI_RESEARCH_PROVIDER + PI_RESEARCH_MODEL) or, if you use pi, via ~/.pi/agent/auth.json."
+    problem: "No model or API key is configured for pi-research. Provide credentials via environment variables (PI_RESEARCH_API_KEY + PI_RESEARCH_PROVIDER + PI_RESEARCH_MODEL) or, if you use pi, via pi's configuration (a provider entry in ~/.pi/agent/auth.json, or a per-provider apiKey in ~/.pi/agent/models.json)."
   };
 }
 function configBlock(det, extraNote) {
@@ -23035,7 +23084,7 @@ function reportError(err, what, json) {
   const lower = msg2.toLowerCase();
   const isConfigError = lower.includes("no llm model available") || lower.includes("not found in pi") || lower.includes("no api key") || lower.includes("provider must be specified") || lower.includes("invalid model string") || lower.includes("authentication") || lower.includes("unauthorized") || lower.includes("api key");
   const isRateLimit = lower.includes("429") || lower.includes("rate limit") || lower.includes("too many requests");
-  const exitCode = isConfigError ? EXIT.CONFIG : EXIT.SOFTWARE;
+  const exitCode = isConfigError && !isRateLimit ? EXIT.CONFIG : EXIT.SOFTWARE;
   if (json) {
     const payload = { ok: false, error: msg2, exitCode };
     if (process.env["PI_RESEARCH_DEBUG"] === "true" && err instanceof Error && err.stack) {
@@ -23044,18 +23093,18 @@ function reportError(err, what, json) {
     toStdout(pretty(payload));
     return exitCode;
   }
-  if (isConfigError) {
+  if (isRateLimit) {
     toStderr(`
-Error: pi-research ${what} failed: ${msg2}
-
-${configBlock(detectCredentials())}
+Error: pi-research ${what} halted: provider rate limit reached. Wait a moment and retry.
+  ${msg2}
 `);
     return exitCode;
   }
-  if (isRateLimit) {
+  if (isConfigError) {
     toStderr(`
-Error: pi-research ${what} halted: provider rate limit reached. Wait a moment and retry.
-  ${msg2}
+Error: pi-research ${what} failed: ${msg2}
+
+${configBlock(detectCredentials())}
 `);
     return exitCode;
   }

package/docs/CONFIGURATION.md

@@ -132,7 +132,7 @@ API keys
 
 | Variable | Description |
 |----------|-------------|
-| `PI_RESEARCH_API_KEY` / `PI_RESEARCH_PROVIDER` | Explicit LLM credentials for SDK / CLI mode (not needed when pi's configuration — `~/.pi/agent/auth.json` — supplies the key). On the CLI / agent skill both can also live in `config.env` / `cli.env`. The provider is required alongside the key, or inferred from a `provider/model-id` `PI_RESEARCH_MODEL`. |
+| `PI_RESEARCH_API_KEY` / `PI_RESEARCH_PROVIDER` | Explicit LLM credentials for SDK / CLI mode (not needed when pi's configuration supplies the key). On the CLI / agent skill both can also live in `config.env` / `cli.env`. The provider is required alongside the key, or inferred from a `provider/model-id` `PI_RESEARCH_MODEL`. |
 | `STACKEXCHANGE_API_KEY` | Raises the Stack Exchange tool's limit from 300/day to 10,000/day. Obtain at <https://stackapps.com/apps/oauth>. |
 | `GITHUB_TOKEN` | Raises the security tool's GitHub Advisory limit from 60/hr to 5000/hr (any default-scope token). |
 | `NVD_API_KEY` | Raises the security tool's NVD limit ~10× and tightens request spacing. Request at <https://nvd.nist.gov/developers/request-an-api-key>. Recommended when using severity-filtered security searches: those issue a second (CVSS v2) NVD query to catch v2-only CVEs, which roughly doubles request time against the 6 s/request unauthenticated throttle. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "A set of web research tools (search, scrape, and others) and research agent system that uses them safely and efficiently.",
   "type": "module",
   "private": false,

package/skills/pi-research/SKILL.md

@@ -2,7 +2,7 @@
 name: pi-research
 description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
 license: MIT
-metadata: { "author": "Lincoln Deen", "version": "1.0.3", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.0.4", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 

package/skills/pi-research/references/configuration.md

@@ -15,8 +15,8 @@ to configure (no research runs).
    export PI_RESEARCH_MODEL=openai/gpt-4o    # provider/model-id
    ```
 2. **Global config** `~/.pi/research/config.env` (same KEY=VALUE keys; read at startup).
-3. **pi configuration** (if you use `pi`): the API key comes from `~/.pi/agent/auth.json`
-   automatically — `PI_RESEARCH_MODEL` must still be set (env or `config.env`).
+3. **pi configuration** (if you use `pi`): the API key comes from your pi
+   configuration automatically — `PI_RESEARCH_MODEL` must still be set (env or `config.env`).
 
 Real env vars always win. Optional CLI-only overlay `~/.pi/research/cli.env` layers
 over `config.env` for the CLI only. Precedence:

package/src/cli.ts

@@ -39,6 +39,7 @@ import { validateInitialLink, MAX_INITIAL_LINKS } from './utils/url-utils.ts';
 import { exportResearchReport, appendExportMessage } from './utils/research-export.ts';
 import { getConfig, getGlobalConfigDir, getGlobalEnvFilePath, getInterfaceEnvFilePath, saveConfig, resetConfig, describeKnowledgeStoreMode, isProjectScopedKey, parseDotEnv } from './config.ts';
 import { getAgentDir } from '@earendil-works/pi-coding-agent';
+import { buildModelRegistry, safeGetAvailable } from './core/llm/model-registry-factory.ts';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -226,6 +227,32 @@ function fileExists(p: string): boolean {
   }
 }
 
+/**
+ * Are keys usable from pi's configuration? Answered by pi's OWN semantics, not
+ * by file presence: build pi's model registry (two small JSON reads — no
+ * services, network, or native deps) and ask for the authed subset. That check
+ * (`hasConfiguredAuth`) covers every source the registry consults at call
+ * time: an auth.json provider entry (api-key or OAuth), a per-provider apiKey
+ * embedded in models.json (env-template aware), and provider env vars like
+ * OPENAI_API_KEY. File presence alone is neither necessary (keys can live in
+ * models.json / env with no auth.json) nor sufficient (auth.json can be `{}`).
+ */
+function piKeysAvailable(piAuthPresent: boolean, provider?: string): boolean {
+  try {
+    const available = safeGetAvailable(buildModelRegistry(undefined, undefined));
+    if (!provider) return available.length > 0;
+    // Provider known (from the configured provider/model-id): keys must exist
+    // for THAT provider — a key for some other provider would pass pre-flight
+    // and then die on the first LLM call ("No API key found for <provider>").
+    return available.some((m) => m.provider === provider);
+  } catch {
+    // Cannot inspect (e.g. malformed models.json) — fall back to file
+    // presence: pre-flight must never block a possibly-working setup; the run
+    // itself reports the precise error.
+    return piAuthPresent;
+  }
+}
+
 export interface CredentialDetection {
   /** Where credentials will come from once initResearchSDK runs. */
   source: 'explicit-env' | 'pi-config' | 'none';
@@ -258,6 +285,9 @@ function detectCredentials(): CredentialDetection {
   // Provider is either explicit, or inferred from a "provider/id" model string.
   const provider =
     providerEnv ?? (model && model.includes('/') ? model.slice(0, model.indexOf('/')) : undefined);
+  // Provider-aware when the configured model names one: a key for a DIFFERENT
+  // provider must not greenlight this run.
+  const piKeysUsable = piKeysAvailable(piAuthPresent, provider);
 
   // --- Explicit API-key path -------------------------------------------------
   if (apiKey) {
@@ -300,13 +330,13 @@ function detectCredentials(): CredentialDetection {
     };
   }
 
-  // --- pi configuration path (key from auth.json) -----------------------------
-  if (piAuthPresent) {
-    // Keys come from auth.json, but the MODEL must be configured explicitly:
-    // the standalone CLI / agent skill run only on the configured model — they
-    // never follow the model selected inside the pi extension, and silently
-    // falling back to the registry's first authed entry picks a model nobody
-    // chose. Fail fast here (pre-flight, before any SDK init).
+  // --- pi configuration path (key from auth.json, models.json, or provider env) ---
+  if (piKeysUsable) {
+    // Keys come from pi's configuration, but the MODEL must be configured
+    // explicitly: the standalone CLI / agent skill run only on the configured
+    // model — they never follow the model selected inside the pi extension, and
+    // silently falling back to the registry's first authed entry picks a model
+    // nobody chose. Fail fast here (pre-flight, before any SDK init).
     if (!model) {
       return {
         source: 'pi-config',
@@ -317,7 +347,7 @@ function detectCredentials(): CredentialDetection {
         piAuthPresent,
         piModelsPresent,
         problem:
-          'pi credentials were found (auth.json), but no research model is configured. ' +
+          'pi credentials were found (in pi\'s configuration), but no research model is configured. ' +
           'The standalone CLI / agent skill run only on an explicitly configured model — they do not ' +
           'follow the model selected inside the pi extension. Set PI_RESEARCH_MODEL to a ' +
           '"provider/model-id" (in the environment, or in config.env / cli.env below).',
@@ -325,7 +355,7 @@ function detectCredentials(): CredentialDetection {
     }
     return {
       source: 'pi-config',
-      apiKeyConfigured: true, // key lives in auth.json; SDK reads it
+      apiKeyConfigured: true, // key lives in pi's configuration; the SDK reads it at call time
       provider,
       model,
       modelFrom,
@@ -346,7 +376,8 @@ function detectCredentials(): CredentialDetection {
     problem:
       'No model or API key is configured for pi-research. Provide credentials via environment ' +
       'variables (PI_RESEARCH_API_KEY + PI_RESEARCH_PROVIDER + PI_RESEARCH_MODEL) or, if you use ' +
-      'pi, via ~/.pi/agent/auth.json.',
+      "pi, via pi's configuration (a provider entry in ~/.pi/agent/auth.json, or a per-provider " +
+      'apiKey in ~/.pi/agent/models.json).',
   };
 }
 
@@ -763,8 +794,12 @@ function reportError(err: unknown, what: string, json?: boolean): number {
     lower.includes('unauthorized') ||
     lower.includes('api key');
 
+  // Rate limits win over config-shaped matches: a provider 429 often mentions
+  // "api key" in its body (e.g. "rate limit exceeded for this api key"), and
+  // classifying that as a setup problem sends the user to reconfigure a
+  // perfectly working key instead of waiting out the limit.
   const isRateLimit = lower.includes('429') || lower.includes('rate limit') || lower.includes('too many requests');
-  const exitCode = isConfigError ? EXIT.CONFIG : EXIT.SOFTWARE;
+  const exitCode = isConfigError && !isRateLimit ? EXIT.CONFIG : EXIT.SOFTWARE;
 
   // --json: emit a structured error on stdout so a machine consumer never has to
   // special-case plain-text stderr. Mirrors the { ok: true, ... } success shape.
@@ -777,15 +812,15 @@ function reportError(err: unknown, what: string, json?: boolean): number {
     return exitCode;
   }
 
-  if (isConfigError) {
-    toStderr(`\nError: pi-research ${what} failed: ${msg}\n\n${configBlock(detectCredentials())}\n`);
-    return exitCode;
-  }
-  // Rate limits are operational, not fatal setup problems.
+  // Rate limits are operational, not fatal setup problems — checked FIRST.
   if (isRateLimit) {
     toStderr(`\nError: pi-research ${what} halted: provider rate limit reached. Wait a moment and retry.\n  ${msg}\n`);
     return exitCode;
   }
+  if (isConfigError) {
+    toStderr(`\nError: pi-research ${what} failed: ${msg}\n\n${configBlock(detectCredentials())}\n`);
+    return exitCode;
+  }
   toStderr(`\nError: pi-research ${what} failed: ${msg}\n`);
   if (process.env['PI_RESEARCH_DEBUG'] === 'true' && err instanceof Error && err.stack) {
     toStderr('\n' + err.stack + '\n');

package/src/core/llm/model-registry-factory.ts

@@ -123,12 +123,13 @@ export function buildModelRegistry(apiKey?: string, provider?: string): ModelReg
     );
   }
 
-  // No explicit key: use the user's pi auth storage and model list if available.
+  // No explicit key: use the user's pi configuration when EITHER file exists.
   // ModelRegistry.create() reads embedded apiKeys from models.json providers
-  // directly (via providerRequestConfigs), so glm-coding and other custom
-  // providers with embedded keys are visible to hasConfiguredAuth() without
-  // needing to duplicate them into AuthStorage.
-  if (fs.existsSync(authPath)) {
+  // directly (via providerRequestConfigs), so custom providers with embedded
+  // keys work with no auth.json at all — auth.json presence must not gate
+  // models.json (AuthStorage.create tolerates a missing file). Env provider
+  // keys (e.g. OPENAI_API_KEY) are honored by AuthStorage in every branch.
+  if (fs.existsSync(authPath) || fs.existsSync(modelsJsonPath)) {
     const authStorage = AuthStorage.create(authPath);
     return ModelRegistry.create(
       authStorage,
@@ -152,7 +153,17 @@ export function constructMinimalModel(provider: string, modelId: string, _apiKey
     provider,
     id: modelId,
     name: modelId,
-    api: provider === 'openai' ? 'openai-completions' : (provider + '-conversations' as any),
+    // Map to a REAL pi-ai api id — "<provider>-conversations" is not one, and a
+    // keyed no-registry setup would pass pre-flight then die on the first call.
+    // Unknown providers default to the OpenAI-compatible protocol, which is what
+    // virtually every third-party endpoint (openrouter, groq, cerebras, …) speaks.
+    api: ({
+      openai: 'openai-completions',
+      anthropic: 'anthropic-messages',
+      google: 'google-generative-ai',
+      gemini: 'google-generative-ai',
+      mistral: 'mistral-conversations',
+    } as Record<string, string>)[provider] ?? 'openai-completions',
     baseUrl: '', // Provider-specific base URLs are handled by pi-ai internal registry
     reasoning: false,
     input: ['text'],

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

@@ -9,7 +9,7 @@ import { type Model } from '@earendil-works/pi-ai';
 import { logger } from '../logger.ts';
 import { safeUnref } from '../utils/safe-unref.ts';
 import { metrics } from '../utils/metrics.ts';
-import { getSteeringMessages, consumeQueuedMessages, getActiveSteeringMessages } from './session-state.ts';
+import { getSteeringMessages, consumeQueuedMessages, getActiveSteeringMessages, getFailedResearchers, getResearcherFailureReasons } from './session-state.ts';
 import { MAX_EXTRA_ROUNDS_WITH_STEERING } from '../constants.ts';
 import {
   getMaxRounds,
@@ -486,7 +486,22 @@ export class DeepResearchOrchestrator {
               logger.warn(`[DeepOrchestrator] LLM returned empty synthesis for ${researchId}, building fallback from ${synthesisService.getReportCount(researchId)} reports`);
               result = synthesisService.buildFallbackSynthesis(researchId, this.currentRound);
           } else {
-              result = 'Research completed but no summary was generated.';
+              // ZERO reports were collected — the run produced nothing groundable.
+              // With the default single-researcher plan the fast-stop threshold
+              // (MAX_FAILED_RESEARCHERS = 2) never trips, so a lone researcher that
+              // exhausts its retries (e.g. a provider rate limit) used to land here
+              // and return a hollow "no summary was generated" string on the SUCCESS
+              // path — exit 0. That is a FAILED run: throw, and surface the recorded
+              // root causes so the user sees the 429/model error, not a shrug.
+              const failedIds = getFailedResearchers(this.options.sessionId, researchId);
+              const reasons = getResearcherFailureReasons(this.options.sessionId, researchId);
+              const causes = failedIds
+                .map((id) => `researcher ${id}: ${reasons[id] ?? 'no usable report'}`)
+                .join('; ');
+              throw new Error(
+                'Research produced no report — no source material was collected' +
+                (causes ? `. Causes: ${causes}` : '.')
+              );
           }
       }
 

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

@@ -358,8 +358,9 @@ export class ResearchOrchestrationService implements IResearchOrchestration {
             logger.debug(`[ResearchOrchestrationService] Researcher ${id} cancelled (aborted).`);
           } else {
             logger.error(`[ResearchOrchestrationService] Researcher ${id} failed: ${errMsg}`);
-            // Record failure for stopping logic
-            recordResearcherFailure(sessionId, researchId, id);
+            // Record failure (with its root cause) for stopping logic and for the
+            // zero-report failure surfaced at synthesis time.
+            recordResearcherFailure(sessionId, researchId, id, errMsg);
             // Notify observer
             observer?.onResearcherFailure?.(id, errMsg);
           }

package/src/orchestration/researcher-executor.ts

@@ -69,7 +69,7 @@ export async function runResearcher(options: RunResearcherOptions): Promise<void
     // use), recording under ctx.sessionId would file this no-links skip under a
     // different id than shouldStopResearch() checks, so the fast-stop guard would
     // under-count exactly the broad-search-failure case it exists to catch.
-    recordResearcherFailure(sessionId, researchId, id);
+    recordResearcherFailure(sessionId, researchId, id, 'no initial search results or historical links (search produced nothing usable)');
     metrics.increment('researcher_skipped_total', 1, { mode: 'deep', complexity: String(complexity), reason: 'no_initial_links' });
     observer?.onResearcherFailure?.(id, 'No initial search results or historical links available');
     return;

package/src/orchestration/session-state.ts

@@ -26,6 +26,8 @@ const MAX_STEERING_MESSAGE_LENGTH = 2000;
 interface PiSessionState {
   /** Map of research run ID → array of failed researcher IDs */
   failures: Map<string, string[]>;
+  /** Map of research run ID → (researcher ID → first failure reason) */
+  failureReasons: Map<string, Map<string, string>>;
   /** Ordered list of research run IDs for TUI stacking (Index 0 = oldest/bottom-most) */
   order: string[];
   /** Registry of panel states for each research run */
@@ -70,6 +72,7 @@ function getPiState(piSessionId: string | undefined): PiSessionState {
   if (!state) {
     state = {
       failures: new Map(),
+      failureReasons: new Map(),
       order: [],
       panels: new Map(),
       aborts: new Map(),
@@ -392,6 +395,7 @@ export function refreshAllSessions(piSessionId: string | undefined): void {
         for (const id of state.order) {
           if (!validIds.includes(id)) {
             state.failures.delete(id);
+            state.failureReasons.delete(id);
             state.panels.delete(id);
           }
         }
@@ -454,6 +458,7 @@ export function startResearchSession(piSessionId: string | undefined, customRese
   const sid = normalizeSessionId(piSessionId);
   const state = getPiState(sid);
   state.failures.set(researchId, []);
+  state.failureReasons.set(researchId, new Map());
   return researchId;
 }
 
@@ -501,6 +506,7 @@ export function endResearchSession(piSessionId: string | undefined, researchId:
   if (!state) return;
 
   state.failures.delete(researchId);
+  state.failureReasons.delete(researchId);
   state.panels.delete(researchId);
   state.aborts.delete(researchId);
 
@@ -525,6 +531,7 @@ export function endResearchSession(piSessionId: string | undefined, researchId:
     } else {
       // Clear research-specific state but preserve the session and steering
       state.failures.clear();
+      state.failureReasons.clear();
       state.aborts.clear();
     }
   }
@@ -563,12 +570,28 @@ export function isBottomMostSession(piSessionId: string | undefined, researchId:
 /**
  * Record a researcher failure
  */
-export function recordResearcherFailure(piSessionId: string | undefined, researchId: string, researcherId: string): void {
+export function recordResearcherFailure(piSessionId: string | undefined, researchId: string, researcherId: string, reason?: string): void {
   const sid = normalizeSessionId(piSessionId);
   const state = getPiState(sid);
   const failures = state.failures.get(researchId) || [];
   failures.push(researcherId);
   state.failures.set(researchId, failures);
+  if (reason) {
+    const reasons = state.failureReasons.get(researchId) ?? new Map<string, string>();
+    // Keep the FIRST reason per researcher — the root cause; retries repeat it.
+    if (!reasons.has(researcherId)) reasons.set(researcherId, reason);
+    state.failureReasons.set(researchId, reasons);
+  }
+}
+
+/**
+ * Get the recorded failure reason per failed researcher (first failure wins).
+ */
+export function getResearcherFailureReasons(piSessionId: string | undefined, researchId: string): Record<string, string> {
+  const sid = normalizeSessionId(piSessionId);
+  const state = getPiState(sid);
+  const reasons = state.failureReasons.get(researchId);
+  return reasons ? Object.fromEntries(reasons) : {};
 }
 
 /**
@@ -610,9 +633,18 @@ export function getResearchStopMessage(piSessionId: string | undefined, research
   // search engine blocking" here mis-sends the user to debug their network; the
   // readiness probes do not even run a search, so a failure is not evidence of bot
   // blocking.
+  // Lead with the RECORDED errors when we have them — the actual root cause
+  // (e.g. a provider 429) beats generic guidance every time.
+  const state = getPiState(sid);
+  const reasons = state.failureReasons.get(researchId);
+  const recorded = reasons && reasons.size > 0
+    ? ['Recorded errors:', ...[...reasons].map(([id, r]) => `• researcher ${id}: ${r}`), '']
+    : [];
+
   return [
     `Research stopped: ${count} researcher(s) did not return a usable report: ${failed.join(', ')}.`,
     '',
+    ...recorded,
     'Most likely cause — the research model could not produce grounded results:',
     '• Try a more capable research model. Very small or "thinking-only" models often',
     '  emit no final text after their tool calls, which fails every researcher.',

package/src/sdk.ts

@@ -236,6 +236,19 @@ 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
+  // seeded from the config (the CLI does that).
+  if (options.model) {
+    const explicit = typeof options.model === 'string'
+      ? options.model
+      : `${(options.model as Model<any>).provider}/${(options.model as Model<any>).id}`;
+    globalConfig = { ...globalConfig, RESEARCH_MODEL: explicit };
+  }
+
   // Infer provider from the effective model if not explicitly provided. The
   // effective model is the explicit option first, else the configured
   // RESEARCH_MODEL — the same precedence the resolve below uses.