@lincoln504/pi-research 1.0.2 → 1.0.4

package/README.md

@@ -63,7 +63,7 @@ pi install npm:@lincoln504/pi-research
 
 See [Agent skill](docs/AGENT-SKILL.md) or [SDK](docs/SDK.md) for standalone (no pi extension) installation.
 
-Then configure a model and key — set `PI_RESEARCH_MODEL` (e.g. `openai/gpt-4o`) plus `PI_RESEARCH_API_KEY` and `PI_RESEARCH_PROVIDER`, either as environment variables or in `~/.pi/research/config.env`. See [Configuration](docs/CONFIGURATION.md). (The pi extension needs no key — it uses pi's own auth.)
+The pi extension works out of the box — it runs on your pi session's model and pi's own configuration. Standalone use (agent skill / CLI / SDK) requires a configured model: set `PI_RESEARCH_MODEL` (e.g. `openai/gpt-4o`) as an environment variable or in `~/.pi/research/config.env`, plus `PI_RESEARCH_API_KEY` if you don't use pi. See [Configuration](docs/CONFIGURATION.md).
 
 The first install pulls the stealth browser engine, which takes a few minutes.
 

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,14 +22034,19 @@ async function _doInit(options = {}) {
   }
   globalApiKey = options.apiKey || process.env["PI_RESEARCH_API_KEY"];
   let parsedProvider = options.provider || process.env["PI_RESEARCH_PROVIDER"];
-  if (!parsedProvider && options.model) {
-    if (typeof options.model === "string") {
-      const slashIdx = options.model.indexOf("/");
+  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") {
+      const slashIdx = effectiveModel.indexOf("/");
       if (slashIdx > 0) {
-        parsedProvider = options.model.slice(0, slashIdx);
+        parsedProvider = effectiveModel.slice(0, slashIdx);
       }
-    } else if (options.model.provider) {
-      parsedProvider = options.model.provider;
+    } else if (effectiveModel.provider) {
+      parsedProvider = effectiveModel.provider;
     }
   }
   if (globalApiKey && !parsedProvider) {
@@ -22015,7 +22054,16 @@ async function _doInit(options = {}) {
   }
   globalRegistry = buildModelRegistry(globalApiKey, parsedProvider);
   try {
-    globalModel = resolveModel(globalRegistry, typeof options.model === "string" ? options.model : void 0, parsedProvider, globalApiKey);
+    if (effectiveModel && typeof effectiveModel === "object" && effectiveModel.id) {
+      globalModel = effectiveModel;
+    } else {
+      globalModel = resolveModel(
+        globalRegistry,
+        typeof effectiveModel === "string" ? effectiveModel : void 0,
+        parsedProvider,
+        globalApiKey
+      );
+    }
     globalContainer = getServiceContainer();
     registerCoreServices(globalContainer);
     registerInfrastructureServices(globalContainer);
@@ -22465,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 {
@@ -22583,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);
@@ -22594,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 {
@@ -22629,11 +22688,23 @@ function detectCredentials() {
       piModelsPresent
     };
   }
-  if (piAuthPresent) {
+  if (piKeysUsable) {
+    if (!model) {
+      return {
+        source: "pi-config",
+        apiKeyConfigured: true,
+        provider,
+        model,
+        modelFrom,
+        piAuthPresent,
+        piModelsPresent,
+        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,
@@ -22649,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) {
@@ -22659,14 +22730,14 @@ function configBlock(det, extraNote) {
   lines.push(`  \u2022 base config file:   ${paths.configEnv}`);
   lines.push(`  \u2022 cli overlay:        ${paths.cliIfaceEnv}  (optional; overrides base for this CLI / agent skill)`);
   lines.push(`  \u2022 env vars:           PI_RESEARCH_API_KEY / PI_RESEARCH_PROVIDER / PI_RESEARCH_MODEL`);
-  lines.push(`  \u2022 pi auth storage:    ${paths.piAuth}`);
-  lines.push(`  \u2022 pi models:          ${paths.piModels}`);
+  lines.push(`  \u2022 pi config (keys):   ${paths.piAuth}`);
+  lines.push(`  \u2022 pi config (models): ${paths.piModels}`);
   lines.push("");
   lines.push("Detected:");
   lines.push(`  \u2022 credential source:  ${det.source}`);
   lines.push(`  \u2022 api key configured: ${det.apiKeyConfigured}`);
-  lines.push(`  \u2022 provider:           ${det.provider ?? "(unset)"}`);
-  lines.push(`  \u2022 model:              ${det.model ?? "(unset)"}  [from: ${det.modelFrom}]`);
+  lines.push(`  \u2022 provider:           ${det.provider ?? "(unset \u2014 inferred from a provider/model-id model)"}`);
+  lines.push(`  \u2022 model:              ${det.model ? `${det.model}  [from: ${det.modelFrom}]` : "(not set \u2014 set PI_RESEARCH_MODEL, required)"}`);
   lines.push(`  \u2022 pi auth.json:       ${det.piAuthPresent ? "present" : "absent"}`);
   lines.push(`  \u2022 pi models.json:     ${det.piModelsPresent ? "present" : "absent"}`);
   if (extraNote) lines.push(`  \u2022 note:               ${extraNote}`);
@@ -22923,8 +22994,9 @@ uninstall: ${BINARY_NAME} skill uninstall
     } catch (err) {
       return reportError(err, "skill install", s.json);
     }
+    const skillModel = process.env["PI_RESEARCH_MODEL"] ?? getConfig(process.cwd(), "cli").RESEARCH_MODEL;
     if (s.json) {
-      toStdout(pretty({ command: "skill", action: "install", dryRun: !!s.dryRun, results: results2 }));
+      toStdout(pretty({ command: "skill", action: "install", dryRun: !!s.dryRun, results: results2, modelConfigured: Boolean(skillModel) }));
     } else {
       toStdout(`pi-research agent skill \u2014 ${s.dryRun ? "install (dry run)" : "install"}
 
@@ -22934,6 +23006,15 @@ uninstall: ${BINARY_NAME} skill uninstall
       toStdout(`
 The skill activates automatically \u2014 ask the agent to research something.
 `);
+      if (!skillModel) {
+        toStdout(
+          `
+Required: set PI_RESEARCH_MODEL=provider/model-id in ${resolvedConfigPaths().configEnv}
+(or as an env var) \u2014 the skill runs only on this configured model, not your pi
+session model. Verify with: ${BINARY_NAME} status
+`
+        );
+      }
     }
     return results2.some((r) => r.status === "error") ? EXIT.SOFTWARE : EXIT.OK;
   }
@@ -23003,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) {
@@ -23012,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;
   }
@@ -23091,11 +23172,15 @@ COMMANDS
 CONFIGURE
   Credentials are resolved in this order (first match wins):
 
-    env vars:     PI_RESEARCH_API_KEY  PI_RESEARCH_PROVIDER  PI_RESEARCH_MODEL
-    cli overlay:  ${p.cliIfaceEnv}   (optional; this CLI / agent skill only)
-    base config:  ${p.configEnv}
-    pi auth:      ${p.piAuth}
-    pi models:    ${p.piModels}
+    env vars:            PI_RESEARCH_API_KEY  PI_RESEARCH_PROVIDER  PI_RESEARCH_MODEL
+    cli overlay:         ${p.cliIfaceEnv}   (optional; this CLI / agent skill only)
+    base config:         ${p.configEnv}
+    pi config (keys):    ${p.piAuth}
+    pi config (models):  ${p.piModels}
+
+  A model is REQUIRED: set PI_RESEARCH_MODEL to a "provider/model-id". This CLI and
+  the agent skill run only on that configured model \u2014 they do not follow the model
+  selected inside the pi extension.
 
   The pi extension has its own optional overlay file:
     pi extension: ${p.piIfaceEnv}

package/docs/AGENT-SKILL.md

@@ -10,7 +10,8 @@ pi-research software.
 Already running the `pi` extension (`pi install npm:@lincoln504/pi-research`)? You
 already have the engine — install the skill into your other agents with
 `/research-config` → Install in External Agents (see [Installation flow](#installation-flow))
-and skip the rest.
+and skip the install commands below. The model step still applies to you: the
+skill runs on its own configured `PI_RESEARCH_MODEL`, not your pi session's model.
 
 For standalone use without pi, install the engine globally, then link the skill into
 every coding agent detected on this machine:
@@ -24,6 +25,18 @@ pi-research skill install                # link the skill into Claude, Codex, Op
 different skill in the slot, and records what it created so `pi-research skill uninstall`
 removes exactly that. Run `pi-research skill status` to see where it is installed.
 
+Then configure the model research runs on — the skill and standalone CLI use only
+this explicitly configured model (they never follow the model selected inside the
+pi extension) and refuse to start without one:
+
+```sh
+# ~/.pi/research/config.env  (or export as an env var)
+PI_RESEARCH_MODEL=provider/model-id
+```
+
+If you use `pi`, the API key comes from your pi configuration (`~/.pi/agent/auth.json`) automatically; otherwise
+also set `PI_RESEARCH_API_KEY` (same file or env var). See [Configuration](CONFIGURATION.md).
+
 On Windows, run `pi-research` from `cmd` or use `pi-research.cmd`: PowerShell's default
 execution policy (`Restricted`) blocks npm's `.ps1` shims ("running scripts is
 disabled"); or run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once.
@@ -114,8 +127,8 @@ Manual. Symlink the directory into any agent's skills folder yourself:
 ### Prerequisites
 
 - Node.js >= 22.19.0
-- `pi-research` installed where the launcher can find it, plus a model + API key.
-  See [Configuration](CONFIGURATION.md).
+- `pi-research` installed where the launcher can find it, plus a configured model
+  (`PI_RESEARCH_MODEL`) + API key. See [Configuration](CONFIGURATION.md).
 
 ```bash
 npm install -g @lincoln504/pi-research

package/docs/CONFIGURATION.md

@@ -75,7 +75,7 @@ Research
 | `PI_RESEARCH_RETRY_DELAY_MS` | `2000` | 100–10000 | Base delay between retries. |
 | `PI_RESEARCH_WORKER_THREADS` | `4` | 1–10 | Browser worker processes. Higher = more throughput, more CPU/RAM. |
 | `PI_RESEARCH_WORKER_CONCURRENCY` | `2` | 1–10 | Tasks per worker process. |
-| `PI_RESEARCH_MODEL` | _(session model)_ | — | Model override for researcher sub-agents (deep and quick) and knowledge synthesis. In the pi extension the coordinator and evaluator keep using the session model; on the standalone CLI/SDK, when no `--model`/`model` option is given, this also selects the session model itself. Accepts `provider/id` or a bare model id. |
+| `PI_RESEARCH_MODEL` | _(pi: session model; CLI/skill: required)_ | — | The model research runs on. **Required for the standalone CLI / agent skill** — they use only this configured model (never the model selected inside the pi extension) and refuse to start without one. On the SDK it selects the session model when no `model` option is given. In the pi extension it overrides researcher sub-agents and knowledge synthesis, while the coordinator and evaluator keep using the session model. Accepts `provider/id` or a bare model id. |
 | `PI_RESEARCH_DISABLED_TOOLS` | _(none)_ | — | Comma-separated research tools to disable for a run (`search`, `scrape`, `security_search`, `stackexchange`, `youtube_transcript`, `grep`). Removed from every researcher's toolset and named in the coordinator/evaluator prompt. |
 | `PI_RESEARCH_REPORT_EXPORT_ENABLED` (TUI) | `false` | — | Front-ends write a Markdown report to disk and surface its path. |
 | `PI_RESEARCH_REPORT_EXPORT_DIR` | _(smart cwd)_ | — | Pin exported reports to a fixed directory, bypassing the cwd-relative resolution. Useful for the agent skill, which runs from the host agent's arbitrary directory. |
@@ -128,11 +128,11 @@ See the [knowledge store doc](KNOWLEDGE-STORE.md) for what each value does.
 | `PI_RESEARCH_EMBEDDING_MODEL_INIT_TIMEOUT_MS` | `300000` | 10000–600000 | Embedding-model initialization timeout (first-time download can be slow). |
 | `PI_RESEARCH_WEBGPU_REPROBE` | _(unset)_ | — | Set `1` to discard the cached WebGPU-viability verdict and probe again on next use. |
 
-API keys (all optional)
+API keys
 
 | Variable | Description |
 |----------|-------------|
-| `PI_RESEARCH_API_KEY` / `PI_RESEARCH_PROVIDER` | Explicit LLM credentials for SDK / CLI mode (not needed when using pi's own auth). Provider is required alongside the key. |
+| `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/docs/SDK.md

@@ -13,6 +13,13 @@ run the `pi` extension, which keeps its own private copy your scripts can't impo
 npm install @lincoln504/pi-research
 ```
 
+Then pick the model: pass `model` to `initResearchSDK`, or set `PI_RESEARCH_MODEL`
+(env or `~/.pi/research/config.env`). The SDK never follows the model selected
+inside the pi extension; only when neither is set does it fall back to the first
+available model in your pi registry. The API key comes from your pi
+configuration (`~/.pi/agent/auth.json`) automatically, or from the `apiKey`
+option / `PI_RESEARCH_API_KEY` env var.
+
 `src/sdk.ts` is a library for scripts, CI, and custom tooling. It is configured
 from code, not from a global overlay file — there is no `sdk.env`. It reads the
 base `~/.pi/research/config.env` as a baseline, and everything is
@@ -83,7 +90,7 @@ extension and the CLI / agent skill do it when `PI_RESEARCH_REPORT_EXPORT_ENABLE
 
 | Option | Description |
 |--------|-------------|
-| `model` | `"provider/id"` string or a `Model` object. Omit to use the first available pi model. |
+| `model` | `"provider/id"` string or a `Model` object. Omit to use the configured `PI_RESEARCH_MODEL`; only when neither is set does the SDK fall back to the first available pi model. |
 | `apiKey` / `provider` | Explicit credentials (provider required with apiKey). |
 | `config` | `Partial<Config>` overrides, applied over the base/defaults. |
 | `ignoreGlobalConfig` | Skip `config.env` entirely — defaults + `process.env` + `config` only. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.0.2",
+  "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/README.md

@@ -39,8 +39,8 @@ model/key is missing.
 ### Prerequisites
 
 - Node.js >= 22.19.0
-- `pi-research` installed somewhere the launcher can find it, and a model +
-  API key configured. See [`references/configuration.md`](references/configuration.md).
+- `pi-research` installed somewhere the launcher can find it, and a configured
+  model (`PI_RESEARCH_MODEL`) + API key. See [`references/configuration.md`](references/configuration.md).
 
 ```bash
 npm install -g @lincoln504/pi-research

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.2", "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:*)
 ---
 
@@ -91,10 +91,13 @@ On exit 78 the engine prints exact configure locations to stderr — relay verba
 ```
 config file:  ~/.pi/research/config.env
 env vars:     PI_RESEARCH_API_KEY  PI_RESEARCH_PROVIDER  PI_RESEARCH_MODEL
-pi auth:      ~/.pi/agent/auth.json
-pi models:    ~/.pi/agent/models.json
+pi config (keys):    ~/.pi/agent/auth.json   (supplies the API key only)
+pi config (models):  ~/.pi/agent/models.json
 ```
 
+`PI_RESEARCH_MODEL` (a `provider/model-id`) is always required — pi's configuration
+supplies only the key, and the skill never uses the model selected inside the pi extension.
+
 Run `status` for the resolved paths on this machine. Full reference:
 [`references/configuration.md`](references/configuration.md).
 

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

@@ -1,6 +1,8 @@
 ## Configuration
 
-The skill drives the **pi-research** engine, which needs a model + API key.
+The skill drives the **pi-research** engine, which needs an explicitly configured
+model (`PI_RESEARCH_MODEL`) + API key — it runs only on that configured model and
+never follows the model selected inside the pi extension.
 Run `node "<SKILL_DIR>/scripts/run.mjs" status` to print what's detected and where
 to configure (no research runs).
 
@@ -13,7 +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 auth** (if you use `pi`): `~/.pi/agent/auth.json` + `~/.pi/agent/models.json`.
+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:
@@ -23,7 +26,7 @@ over `config.env` for the CLI only. Precedence:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `PI_RESEARCH_MODEL` | session model | Model override for all research sub-tasks. |
+| `PI_RESEARCH_MODEL` | _(required)_ | The `provider/model-id` all research runs on. |
 | `PI_RESEARCH_DEFAULT_RESEARCH_DEPTH` | `1` | Default depth (1–3) when `--depth` omitted. |
 | `PI_RESEARCH_MAX_RESEARCHERS` | `3` | Parallel researchers (1–5). |
 | `PI_RESEARCH_TIMEOUT_MS` | `300000` | Per-researcher timeout (180000–1800000). |
@@ -70,7 +73,7 @@ model/key; message lists the fix) · `70` runtime error (network/provider/intern
   `export PI_RESEARCH_BIN=/path/to/pi-research/dist/cli.mjs` (exact CLI entry;
   checked first — also the escape hatch for unusual Windows shim layouts).
 - **"No model or API key" (78 from engine):** set the three env vars (or config /
-  pi auth), then re-run `status`.
+  pi's configuration), then re-run `status`.
 - **Rate limit (70):** provider returned 429 — wait and retry.
 - **GPU/embedding errors:** set `PI_RESEARCH_EMBEDDING_DEVICE=cpu` (headless/no-GPU).
 

package/skills/pi-research/scripts/run.mjs

@@ -139,10 +139,11 @@ function notInstalled() {
     "    # or, with pi:   pi install npm:@lincoln504/pi-research",
     "    # or point at a copy: export PI_RESEARCH_PATH=/path/to/pi-research",
     "",
-    "After installing, configure a model + API key. Locations:",
+    "After installing, configure the model (PI_RESEARCH_MODEL is required) + API key.",
+    "Locations:",
     `  \u2022 env vars:           PI_RESEARCH_API_KEY / PI_RESEARCH_PROVIDER / PI_RESEARCH_MODEL`,
     `  \u2022 global config file: ${join(home, ".pi", "research", "config.env")}`,
-    `  \u2022 pi auth storage:    ${join(home, ".pi", "agent", "auth.json")}`,
+    `  \u2022 pi config (keys):   ${join(home, ".pi", "agent", "auth.json")}  (supplies the API key only)`,
     "",
     "Run `status` once installed to verify detection.",
     ""

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
@@ -196,7 +197,7 @@ export interface ResolvedConfigPaths {
   cliIfaceEnv: string;
   /** Per-interface overlay for the pi extension (~/.pi/research/pi.env). */
   piIfaceEnv: string;
-  /** pi auth storage (~/.pi/agent/auth.json). */
+  /** pi's key file (~/.pi/agent/auth.json), part of pi's configuration. */
   piAuth: string;
   /** pi model definitions (~/.pi/agent/models.json). */
   piModels: string;
@@ -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,12 +330,32 @@ function detectCredentials(): CredentialDetection {
     };
   }
 
-  // --- pi auth storage path --------------------------------------------------
-  if (piAuthPresent) {
-    // The SDK will resolve a model from the registry (models.json + PI_RESEARCH_MODEL).
+  // --- 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',
+        apiKeyConfigured: true,
+        provider,
+        model,
+        modelFrom,
+        piAuthPresent,
+        piModelsPresent,
+        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 — 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
+      apiKeyConfigured: true, // key lives in pi's configuration; the SDK reads it at call time
       provider,
       model,
       modelFrom,
@@ -326,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).',
   };
 }
 
@@ -342,14 +393,14 @@ function configBlock(det: CredentialDetection, extraNote?: string): string {
   lines.push(`  • base config file:   ${paths.configEnv}`);
   lines.push(`  • cli overlay:        ${paths.cliIfaceEnv}  (optional; overrides base for this CLI / agent skill)`);
   lines.push(`  • env vars:           PI_RESEARCH_API_KEY / PI_RESEARCH_PROVIDER / PI_RESEARCH_MODEL`);
-  lines.push(`  • pi auth storage:    ${paths.piAuth}`);
-  lines.push(`  • pi models:          ${paths.piModels}`);
+  lines.push(`  • pi config (keys):   ${paths.piAuth}`);
+  lines.push(`  • pi config (models): ${paths.piModels}`);
   lines.push('');
   lines.push('Detected:');
   lines.push(`  • credential source:  ${det.source}`);
   lines.push(`  • api key configured: ${det.apiKeyConfigured}`);
-  lines.push(`  • provider:           ${det.provider ?? '(unset)'}`);
-  lines.push(`  • model:              ${det.model ?? '(unset)'}  [from: ${det.modelFrom}]`);
+  lines.push(`  • provider:           ${det.provider ?? '(unset — inferred from a provider/model-id model)'}`);
+  lines.push(`  • model:              ${det.model ? `${det.model}  [from: ${det.modelFrom}]` : '(not set — set PI_RESEARCH_MODEL, required)'}`);
   lines.push(`  • pi auth.json:       ${det.piAuthPresent ? 'present' : 'absent'}`);
   lines.push(`  • pi models.json:     ${det.piModelsPresent ? 'present' : 'absent'}`);
   if (extraNote) lines.push(`  • note:               ${extraNote}`);
@@ -657,12 +708,23 @@ async function cmdSkill(s: NonNullable<ParsedArgs['skill']>): Promise<number> {
     } catch (err) {
       return reportError(err, 'skill install', s.json);
     }
+    // The skill runs only on an explicitly configured model — if none is set yet,
+    // say so right here, at the moment of install (mirrors the TUI install action).
+    const skillModel =
+      process.env['PI_RESEARCH_MODEL'] ?? getConfig(process.cwd(), 'cli').RESEARCH_MODEL;
     if (s.json) {
-      toStdout(pretty({ command: 'skill', action: 'install', dryRun: !!s.dryRun, results }));
+      toStdout(pretty({ command: 'skill', action: 'install', dryRun: !!s.dryRun, results, modelConfigured: Boolean(skillModel) }));
     } else {
       toStdout(`pi-research agent skill — ${s.dryRun ? 'install (dry run)' : 'install'}\n\n`);
       for (const r of results) toStdout(`  ${r.tool.padEnd(10)} ${describeInstall(r)}\n`);
       toStdout(`\nThe skill activates automatically — ask the agent to research something.\n`);
+      if (!skillModel) {
+        toStdout(
+          `\nRequired: set PI_RESEARCH_MODEL=provider/model-id in ${resolvedConfigPaths().configEnv}\n` +
+          `(or as an env var) — the skill runs only on this configured model, not your pi\n` +
+          `session model. Verify with: ${BINARY_NAME} status\n`
+        );
+      }
     }
     return results.some((r) => r.status === 'error') ? EXIT.SOFTWARE : EXIT.OK;
   }
@@ -732,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.
@@ -746,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');
@@ -842,11 +908,15 @@ COMMANDS
 CONFIGURE
   Credentials are resolved in this order (first match wins):
 
-    env vars:     PI_RESEARCH_API_KEY  PI_RESEARCH_PROVIDER  PI_RESEARCH_MODEL
-    cli overlay:  ${p.cliIfaceEnv}   (optional; this CLI / agent skill only)
-    base config:  ${p.configEnv}
-    pi auth:      ${p.piAuth}
-    pi models:    ${p.piModels}
+    env vars:            PI_RESEARCH_API_KEY  PI_RESEARCH_PROVIDER  PI_RESEARCH_MODEL
+    cli overlay:         ${p.cliIfaceEnv}   (optional; this CLI / agent skill only)
+    base config:         ${p.configEnv}
+    pi config (keys):    ${p.piAuth}
+    pi config (models):  ${p.piModels}
+
+  A model is REQUIRED: set PI_RESEARCH_MODEL to a "provider/model-id". This CLI and
+  the agent skill run only on that configured model — they do not follow the model
+  selected inside the pi extension.
 
   The pi extension has its own optional overlay file:
     pi extension: ${p.piIfaceEnv}

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/research-config.ts

@@ -23,7 +23,7 @@ import {
 } from '@earendil-works/pi-tui';
 import { setInteractiveTuiActive, initGlobalTuiController } from './tui/tui-controller.ts';
 import { normalizeSessionId } from './orchestration/session-state.ts';
-import { getConfig, saveConfig, resetConfig, getDbDir } from './config.ts';
+import { getConfig, saveConfig, resetConfig, getDbDir, getGlobalEnvFilePath } from './config.ts';
 import { healthRegistry } from './healthcheck/index.ts';
 import { getService, clearService, tryGetServiceContainerFromCtx } from './core/service-registry.ts';
 import { ServiceNames, IKnowledgeStoreService } from './core/service-interfaces.ts';
@@ -648,6 +648,19 @@ async function installSkillAction(ctx: ExtensionContext, pi: ExtensionAPI): Prom
     }
     lines.push('', 'The skill activates automatically — just ask the agent to pi-research something.');
 
+    // The skill runs only on an explicitly configured model (it never follows the
+    // pi session model) — if none is configured yet, say so right here, at the
+    // moment of install, mirroring the CLI's `skill install` output.
+    const skillModel = process.env['PI_RESEARCH_MODEL'] ?? getConfig(ctx.cwd, 'cli').RESEARCH_MODEL;
+    if (!skillModel) {
+      lines.push(
+        '',
+        '**Required:** set `PI_RESEARCH_MODEL=provider/model-id` in ' +
+        `\`${getGlobalEnvFilePath()}\` (or as an env var) — the skill runs only on ` +
+        'this configured model, not your pi session model.'
+      );
+    }
+
     pi.sendMessage({ customType: 'skill-install-result', content: lines.join('\n'), display: true });
     if (ctx.hasUI) {
       if (ok > 0) ctx.ui.notify(`Skill installed for ${ok} coding agent${ok === 1 ? '' : 's'}.`, 'info');

package/src/sdk.ts

@@ -144,17 +144,21 @@ function _removeSignalHandlers(): void {
  * Options for initializing the Research SDK
  */
 export interface ResearchSDKOptions {
-  /** 
+  /**
    * The LLM model to use for coordination, planning, and evaluation.
-   * If a string, it must match "provider/id" (e.g. "openai/gpt-4o").
-   * If omitted, the first available model in pi's configuration will be used.
+   * If a string, it must match "provider/id" (e.g. "openai/gpt-4o"); a Model
+   * object is used as-is. If omitted, the configured RESEARCH_MODEL
+   * (PI_RESEARCH_MODEL / config.env, or the `config` option) is used; only
+   * when neither is set does the SDK fall back to the first available model
+   * in pi's configuration. The SDK never follows the model selected
+   * interactively inside the pi extension.
    */
   model?: string | Model<any>;
   
   /** 
    * Optional explicit API key for the model. 
    * If provided, `provider` must also be set.
-   * If omitted, pi's global auth storage (~/.pi/agent/auth.json) is used.
+   * If omitted, the key from pi's configuration (~/.pi/agent/auth.json) is used.
    */
   apiKey?: string;
 
@@ -232,15 +236,31 @@ 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'];
 
-  // Infer provider from model if not explicitly provided
-  if (!parsedProvider && options.model) {
-    if (typeof options.model === 'string') {
-      const slashIdx = options.model.indexOf('/');
+  // 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.
+  const effectiveModel = options.model ?? globalConfig.RESEARCH_MODEL;
+  if (!parsedProvider && effectiveModel) {
+    if (typeof effectiveModel === 'string') {
+      const slashIdx = effectiveModel.indexOf('/');
       if (slashIdx > 0) {
-        parsedProvider = options.model.slice(0, slashIdx);
+        parsedProvider = effectiveModel.slice(0, slashIdx);
       }
-    } else if ((options.model as any).provider) {
-      parsedProvider = (options.model as any).provider;
+    } else if ((effectiveModel as any).provider) {
+      parsedProvider = (effectiveModel as any).provider;
     }
   }
 
@@ -252,8 +272,23 @@ async function _doInit(options: ResearchSDKOptions = {}): Promise<void> {
   globalRegistry = sharedBuildModelRegistry(globalApiKey, parsedProvider);
 
   try {
-    // Resolve model using unified logic.
-    globalModel = resolveModel(globalRegistry, typeof options.model === 'string' ? options.model : undefined, parsedProvider, globalApiKey);
+    // 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.
+    if (effectiveModel && typeof effectiveModel === 'object' && (effectiveModel as any).id) {
+      globalModel = effectiveModel as Model<any>;
+    } else {
+      globalModel = resolveModel(
+        globalRegistry,
+        typeof effectiveModel === 'string' ? effectiveModel : undefined,
+        parsedProvider,
+        globalApiKey
+      );
+    }
 
     // Use the global container to ensure internal services can resolve dependencies
     globalContainer = getServiceContainer();