AI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary
Python ai-promptsai-skillblueskyclaudeclaude-codeclawhubdeep-researchhackernewsinstagramopenclawpolymarketrecencyredditresearchsocial-mediatiktoktrendstwitterweb-searchyoutube
feat(perplexity): migrate Sonar integration to the Agent API (#1019)
Sk35ff7b054998
diff --git a/CONFIGURATION.md b/CONFIGURATION.mdindex 33143f91..4e2c6e36 100644--- a/CONFIGURATION.md+++ b/CONFIGURATION.md@@ -160,7 +160,7 @@ python3 skills/last30days/scripts/last30days.py "MCP servers" \| Bluesky | `BSKY_HANDLE` + `BSKY_APP_PASSWORD` | Bluesky items | yes (app password at bsky.app) || TruthSocial | `TRUTHSOCIAL_TOKEN` | TruthSocial items | yes || Web search | one of: `BRAVE_API_KEY`, `EXA_API_KEY`, `SERPER_API_KEY`, `PARALLEL_API_KEY` | `--auto-resolve` and Step 2 supplements | Brave has a free tier; native WebSearch on Claude Code / Codex / Gemini works as a fallback |-| Perplexity Sonar / Search API / Deep Research | `PERPLEXITY_API_KEY` (preferred) or `OPENROUTER_API_KEY` (Sonar fallback) | `INCLUDE_SOURCES=perplexity`; `--deep-research` flag (~$0.90/query) | no |+| Perplexity Agent API / Search API / Deep Research | `PERPLEXITY_API_KEY` (preferred) or `OPENROUTER_API_KEY` (Sonar fallback) | `INCLUDE_SOURCES=perplexity`; `--deep-research` uses background Agent API with a direct key or synchronous Sonar through OpenRouter | no || Caption-free transcription | `GROQ_API_KEY` (free tier, preferred) or `OPENAI_API_KEY` (paid backstop); requires `ffmpeg` | Whisper transcription for audio/video without captions (groundwork: module shipped, not yet auto-invoked by the engine) | Groq free tier is generous; needs ffmpeg installed || Jobs / careers pages | none for public ATS pages; web backend improves fallback discovery | `--hiring-signals` and strong Hiring Signals in standard company reports | yes || Apify (alternate scraper) | `APIFY_API_TOKEN` | fallback for Reddit/TikTok/Instagram when ScrapeCreators is exhausted | yes (limited) |@@ -191,8 +191,10 @@ INCLUDE_SOURCES=tiktok,instagram# Add perplexity to INCLUDE_SOURCES when you want the paid Perplexity source.# PERPLEXITY_API_KEY=<your-perplexity-key># INCLUDE_SOURCES=tiktok,instagram,perplexity-# LAST30DAYS_PERPLEXITY_MODE=sonar # sonar | search | both-# LAST30DAYS_PERPLEXITY_MODEL=sonar-pro # sonar | sonar-pro | sonar-reasoning-pro+# LAST30DAYS_PERPLEXITY_MODE=agent # agent | search | both; sonar is a legacy alias+# LAST30DAYS_PERPLEXITY_AGENT_MODEL=perplexity/sonar+# LAST30DAYS_PERPLEXITY_AGENT_MAX_STEPS=5+# LAST30DAYS_PERPLEXITY_AGENT_MAX_OUTPUT_TOKENS=4096 # required for anthropic/*# X authentication (one option only)AUTH_TOKEN=<your-auth-token>@@ -220,33 +222,44 @@ After editing: `chmod 600 ~/.config/last30days/.env` (or `chmod 600 .claude/last### Perplexity source modes-Perplexity is a paid opt-in source. A direct `PERPLEXITY_API_KEY` unlocks first-party Perplexity features. `OPENROUTER_API_KEY` remains a Sonar compatibility fallback only; Perplexity Search API and async Deep Research call Perplexity directly.+Perplexity is a paid opt-in source. A direct `PERPLEXITY_API_KEY` enables the Agent API, Search API, and background Deep Research. Existing `OPENROUTER_API_KEY` installs remain compatible through synchronous Sonar: `perplexity/sonar-pro` for normal synthesis and `perplexity/sonar-deep-research` for `--deep-research`. Search API and Agent API features still require the direct key.`LAST30DAYS_PERPLEXITY_MODE` controls normal `perplexity` source runs:| Value | Behavior | Calls ||---|---|---|-| `sonar` (default) | Sonar synthesis plus citations. | one Sonar call |-| `search` | Raw ranked Search API rows; best when you want source aggregation over prose. | one Search API call |-| `both` | Sonar synthesis plus raw ranked Search API rows, deduped by URL. | one Search API call and one Sonar call |+| `agent` (default) | Direct key: controlled Agent API synthesis with required `web_search`. OpenRouter-only: synchronous Sonar fallback. | at most one paid synthesis call per last30days run |+| `sonar` | Direct key: deprecated alias for `agent`. OpenRouter-only: synchronous Sonar fallback. | at most one paid synthesis call per last30days run |+| `search` | Direct key: raw ranked Search API rows. OpenRouter-only: falls back to synchronous Sonar. | at most one paid call per last30days run |+| `both` | Direct key: Agent synthesis plus Search rows. OpenRouter-only: falls back to synchronous Sonar. | direct: at most two paid calls; OpenRouter: at most one |-`--deep-research` ignores `LAST30DAYS_PERPLEXITY_MODE` and uses `sonar-deep-research`. With `PERPLEXITY_API_KEY`, it submits to Perplexity's async Sonar endpoint and polls with a hard wall-clock timeout. The async request uses a deterministic idempotency key derived from the request body. If the request is still running at timeout, fails remotely, or polling hits a transport/rate-limit error after the async id exists, the raw artifact records the async request id, idempotency key, last status, lifecycle timestamps returned by Perplexity, poll count, and timeout/error fields so you can inspect or resume by id outside the run. With only `OPENROUTER_API_KEY`, it keeps the OpenRouter synchronous fallback.+With a direct key, normal `agent` mode uses the controlled `last30days-controlled-web-search/v1` profile: `perplexity/sonar`, a bounded `max_steps`, a local instruction, and only the configured `web_search` tool. It forces that tool for citation-critical grounding. It does not enable sandbox, file, finance, MCP, or function tools. OpenRouter fallback keeps the older OpenAI-compatible Sonar request and does not claim Agent API controls.++The engine routes every normal Perplexity mode through one whole-topic planner subquery per command, including competitor fanout, and does not repeat it during thin-source retries. A generic source-fetch override cannot raise this paid-call cap.++`LAST30DAYS_PERPLEXITY_AGENT_PRESET` is a separate explicit opt-in for a mutable Perplexity preset (`fast`, `low`, `medium`, or `high`). Presets can change their model, prompt, tools, cost, and output behavior. The engine still supplies its configured `web_search` tool so date, domain, location, result-count, and context constraints merge with the preset; other preset tools can remain enabled. Do not set this variable when you need the controlled profile. The engine never selects a preset automatically for normal runs.++`--deep-research` requires a normal positional topic and ignores `LAST30DAYS_PERPLEXITY_MODE`. With a direct key it starts at most one Agent API background run with the explicit dynamic `high` preset. With only OpenRouter it preserves the older synchronous `perplexity/sonar-deep-research` fallback. It cannot be combined with discovery, drill, cached-only, competitor, or vs-mode. This is a separate paid action. The engine caps it at one planner subquery and does not repeat it during thin-source retries. Direct background runs merge the configured `web_search` constraints with the preset, but the provider controls its other tools and can change them. A local timeout stops waiting but does not stop a direct remote run. Direct artifacts retain the served model, response ID, provider status, incomplete reason, poll count, timeout, and safe error metadata; OpenRouter artifacts retain the served model, response ID, usage, and citation count. Neither stores request headers or raw tool traces.Perplexity-specific env vars:| Env var | Default | Applies to | Notes ||---|---|---|---|-| `LAST30DAYS_PERPLEXITY_MODE` | `sonar` | normal Perplexity source runs | `sonar`, `search`, or `both`; `search` and `both` require `PERPLEXITY_API_KEY`. |-| `LAST30DAYS_PERPLEXITY_MODEL` | `sonar-pro` | direct Sonar only | Supported: `sonar`, `sonar-pro`, `sonar-reasoning-pro`. `--deep-research` forces `sonar-deep-research`. |-| `LAST30DAYS_PERPLEXITY_MAX_RESULTS` | `10` | Search API | Clamped to Perplexity's 1..20 range. |-| `LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE` | provider default | Search API | `low`, `medium`, or `high`; omitted unless set. |-| `LAST30DAYS_PERPLEXITY_SEARCH_MODE` | provider default | direct Sonar | `web`, `academic`, or `sec`. |-| `LAST30DAYS_PERPLEXITY_DOMAIN_FILTER` | unset | Search API and direct Sonar | Comma-separated domains, max 20. |-| `LAST30DAYS_PERPLEXITY_LANGUAGE_FILTER` | unset | Search API and direct Sonar | Comma-separated ISO 639-1 language codes, max 20. |-| `LAST30DAYS_PERPLEXITY_COUNTRY` | unset | Search API | Two-letter country code such as `US`. |-| `LAST30DAYS_PERPLEXITY_RECENCY_FILTER` | unset | Search API and direct Sonar | `hour`, `day`, `week`, `month`, or `year`. |-| `LAST30DAYS_PERPLEXITY_REASONING_EFFORT` | unset | direct Sonar | `minimal`, `low`, `medium`, or `high`. |-| `LAST30DAYS_PERPLEXITY_DEEP_TIMEOUT_SECONDS` | `600` | direct async Deep Research | Wall-clock polling deadline. |+| `LAST30DAYS_PERPLEXITY_MODE` | `agent` | normal Perplexity source runs | `agent`, `search`, or `both`; `sonar` remains a deprecated alias for `agent`. |+| `LAST30DAYS_PERPLEXITY_AGENT_MODEL` | `perplexity/sonar` | controlled Agent profile | Explicit Agent model for normal synthesis. |+| `LAST30DAYS_PERPLEXITY_AGENT_MAX_STEPS` | `5` | controlled Agent profile | Clamped to the last30days safety range 1..15. |+| `LAST30DAYS_PERPLEXITY_AGENT_MAX_OUTPUT_TOKENS` | `4096` for `anthropic/*` models | controlled Agent profile | Required for explicit Anthropic models; clamped to the last30days safety range 1..32768. |+| `LAST30DAYS_PERPLEXITY_AGENT_TIMEOUT_SECONDS` | `120` | controlled Agent profile | Synchronous request timeout, clamped to 1..600 seconds. |+| `LAST30DAYS_PERPLEXITY_AGENT_PRESET` | unset | normal Agent runs | Explicit mutable preset only: `fast`, `low`, `medium`, or `high`. It replaces the controlled profile for that run. |+| `LAST30DAYS_PERPLEXITY_MAX_RESULTS` | `10` | Search API and all Agent `web_search` requests | Clamped to 1..20. |+| `LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE` | provider default | Search API and all Agent `web_search` requests | `low`, `medium`, or `high`; omitted unless set. |+| `LAST30DAYS_PERPLEXITY_DOMAIN_FILTER` | unset | Search API and all Agent `web_search` requests | Comma-separated domains, max 20. |+| `LAST30DAYS_PERPLEXITY_LANGUAGE_FILTER` | unset | Search API only | Comma-separated ISO 639-1 language codes. Agent API has no equivalent. |+| `LAST30DAYS_PERPLEXITY_COUNTRY` | unset | Search API and all Agent `web_search` requests | Two-letter country code such as `US`. |+| `LAST30DAYS_PERPLEXITY_RECENCY_FILTER` | unset | Search API and all Agent `web_search` requests | `hour`, `day`, `week`, `month`, or `year`; exact date filters take precedence. |+| `LAST30DAYS_PERPLEXITY_REASONING_EFFORT` | unset | controlled Agent profile | `minimal`, `low`, `medium`, or `high`. |+| `LAST30DAYS_PERPLEXITY_DEEP_TIMEOUT_SECONDS` | `600` | direct Agent API background Deep Research | Wall-clock polling deadline; remote work can continue after a local timeout. OpenRouter fallback is synchronous. |+| `LAST30DAYS_PERPLEXITY_MODEL` / `LAST30DAYS_PERPLEXITY_SEARCH_MODE` | unset | legacy Sonar config | Retained for config-file compatibility. They do not select an Agent API preset or search mode. |### Encrypted credential sources (Keychain / pass)@@ -358,7 +371,7 @@ An explicit `--register` wins over `LAST30DAYS_REGISTER`; the environment/config1. **Gemini** - `GOOGLE_API_KEY` / `GEMINI_API_KEY` / `GOOGLE_GENAI_API_KEY`2. **OpenAI** - `OPENAI_API_KEY` only. Codex ChatGPT auth at `~/.codex/auth.json` is intentionally not used as an OpenAI provider credential.3. **xAI** - `XAI_API_KEY`-4. **OpenRouter** - `OPENROUTER_API_KEY` (Sonar fallback for the Perplexity source / `--deep-research`; also usable as a reasoning provider)+4. **OpenRouter** - `OPENROUTER_API_KEY` (reasoning provider, auto-resolve, and synchronous Sonar fallback for the Perplexity source)5. **Local / deterministic** - always available, lowest qualityWhen you invoke `/last30days` from Claude Code, Codex, or Gemini, the host model **is** the reasoning provider for plan + synthesis - you don't need any of the keys above unless you also run the script headlessly (cron, CI, watchlist).diff --git a/README.de.md b/README.de.mdindex 2d47fd1a..923f04e7 100644--- a/README.de.md+++ b/README.de.md@@ -81,7 +81,7 @@ Wenn du dich mit einem CEO triffst: Hast du alle Tweets und YouTube-Transkripte| **Pinterest** | Visuelle Entdeckung. Pins, gespeicherte Beiträge und Kommentare zu Produkten und Ideen. || **Xiaohongshu (RED)** | Chinesische Signale zu Lifestyle, Produkten und Creators. Wird ausdrücklich mit `--search xhs` angefordert, wenn lokal ein eingeloggtes x-mcp-Browser-Plugin oder ein `xiaohongshu-mcp`-Dienst läuft. || **Bluesky** | Die dezentrale soziale Ebene. AT-Protocol-Beiträge aus der Abwanderung nach Twitter. |-| **Perplexity** | Belegte Sonar-Synthese, Rohtreffer der Search API und Deep Research. |+| **Perplexity** | Gesteuerte Agent-API-Synthese, OpenRouter-Sonar-Fallback, Rohtreffer der Search API und explizite Deep Research. || **Web** | Die redaktionelle Berichterstattung, die Blog-Vergleiche. Ein Signal von vielen, nicht das einzige. |Die Community steuert laufend weitere bei. Truth Social und andere Nischenquellen stecken bereits in der Engine, weitere folgen.@@ -295,7 +295,7 @@ Diese Plattformen haben nichts miteinander zu tun. X weiß nicht, was Reddit den| TikTok + Instagram + Threads + Pinterest + LinkedIn + YouTube-Kommentare | Ein ScrapeCreators-Schlüssel | 10.000 kostenlose Aufrufe, danach nutzungsabhängig || Xiaohongshu (RED) | Ein eingeloggtes x-mcp-Browser-Plugin oder einen `xiaohongshu-mcp`-Dienst laufen lassen und die Quelle mit `--search xhs` pro Durchlauf oder `INCLUDE_SOURCES=xiaohongshu` in `.env` zuschalten; last30days probiert automatisch `http://localhost:18060` und danach `http://host.docker.internal:18060`, oder du setzt `XIAOHONGSHU_API_BASE` für eine eigene URL | Kein last30days-API-Schlüssel nötig; hängt von deinem lokalen Browser-Session-Dienst ab || DripStack (Premium-Finanznewsletter) | Zuschaltbar: `--search dripstack` pro Durchlauf, oder `INCLUDE_SOURCES=dripstack` in `.env` | Kein Schlüssel; kostenlose öffentliche Such-API |-| Perplexity Sonar / Search API / Deep Research | Ein Perplexity-Schlüssel, oder ein OpenRouter-Schlüssel als Sonar-Fallback | Nutzungsabhängig |+| Perplexity Agent API / Search API / Deep Research | Ein Perplexity-Schlüssel, oder ein OpenRouter-Schlüssel als Sonar-Fallback | Nutzungsabhängig; ein direkter Schlüssel aktiviert Agent API und Deep Research im Hintergrund || Websuche | Ein Brave-Search-Schlüssel | 2.000 kostenlose Anfragen pro Monat |### macOS Keychain (optional)diff --git a/README.es.md b/README.es.mdindex deae6b7f..9e3b0ae4 100644--- a/README.es.md+++ b/README.es.md@@ -81,7 +81,7 @@ Si te vas a reunir con un CEO, ¿te has leído todos sus tuits y todas sus trans| **Pinterest** | Descubrimiento visual. Pines, guardados y comentarios sobre productos e ideas. || **Xiaohongshu (RED)** | Señales chinas sobre estilo de vida, productos y creadores. Se pide de forma explícita con `--search xhs` cuando tienes corriendo en local un plugin de navegador x-mcp con sesión iniciada o un servicio `xiaohongshu-mcp`. || **Bluesky** | La capa social descentralizada. Publicaciones de AT Protocol surgidas de la migración posterior a Twitter. |-| **Perplexity** | La síntesis fundamentada de Sonar, los resultados en bruto de la Search API y Deep Research. |+| **Perplexity** | Síntesis controlada con la Agent API, alternativa Sonar mediante OpenRouter, resultados en bruto de la Search API y Deep Research explícita. || **Web** | La cobertura editorial, las comparativas de los blogs. Una señal entre muchas, no la única. |La comunidad no para de sumar fuentes. Truth Social y otras fuentes de nicho ya están en el motor, y vienen más.@@ -295,7 +295,7 @@ Estas plataformas no tienen ninguna relación entre sí. X no sabe lo que piensa| TikTok + Instagram + Threads + Pinterest + LinkedIn + comentarios de YouTube | Una clave de ScrapeCreators | 10.000 llamadas gratis y luego pago por uso || Xiaohongshu (RED) | Ten corriendo un plugin de navegador x-mcp con sesión iniciada o un servicio `xiaohongshu-mcp`, y activa la fuente con `--search xhs` por ejecución o con `INCLUDE_SOURCES=xiaohongshu` en `.env`; last30days prueba automáticamente `http://localhost:18060` y después `http://host.docker.internal:18060`, o usa `XIAOHONGSHU_API_BASE` para una URL propia | No hace falta clave de API de last30days; depende de tu servicio local de sesión de navegador || DripStack (boletines financieros premium) | Opcional: `--search dripstack` por ejecución, o `INCLUDE_SOURCES=dripstack` en `.env` | Sin clave; API de búsqueda pública y gratuita |-| Perplexity Sonar / Search API / Deep Research | Una clave de Perplexity, o una clave de OpenRouter como alternativa para Sonar | Pago por uso |+| Perplexity Agent API / Search API / Deep Research | Una clave de Perplexity, o una clave de OpenRouter como alternativa para Sonar | Pago por uso; una clave directa habilita la Agent API y Deep Research en segundo plano || Búsqueda web | Una clave de Brave Search | 2.000 consultas gratis al mes |### Llavero de macOS (opcional)diff --git a/README.fr.md b/README.fr.mdindex 1700699e..9bb6b320 100644--- a/README.fr.md+++ b/README.fr.md@@ -81,7 +81,7 @@ Si vous rencontrez un PDG, avez-vous lu tous ses tweets et toutes ses transcript| **Pinterest** | La découverte visuelle. Épingles, enregistrements et commentaires sur des produits et des idées. || **Xiaohongshu (RED)** | Les signaux chinois sur le lifestyle, les produits et les créateurs. À demander explicitement avec `--search xhs` quand un plugin de navigateur x-mcp connecté ou un service `xiaohongshu-mcp` tourne en local. || **Bluesky** | La couche sociale décentralisée. Les posts AT Protocol issus de la migration post-Twitter. |-| **Perplexity** | La synthèse Sonar sourcée, les résultats bruts de la Search API et Deep Research. |+| **Perplexity** | Une synthèse contrôlée avec l’Agent API, un repli Sonar via OpenRouter, les résultats bruts de la Search API et Deep Research explicite. || **Web** | La couverture éditoriale, les comparatifs de blogs. Un signal parmi d'autres, pas le seul. |La communauté en ajoute sans cesse. Truth Social et d'autres sources de niche sont déjà dans le moteur, et d'autres arrivent.@@ -295,7 +295,7 @@ Ces plateformes n'ont aucune relation entre elles. X ignore ce que pense Reddit.| TikTok + Instagram + Threads + Pinterest + LinkedIn + commentaires YouTube | Une clé ScrapeCreators | 10 000 appels gratuits, puis paiement à l'usage || Xiaohongshu (RED) | Faites tourner un plugin de navigateur x-mcp connecté ou un service `xiaohongshu-mcp`, puis activez la source avec `--search xhs` pour une exécution ou `INCLUDE_SOURCES=xiaohongshu` dans `.env` ; last30days teste automatiquement `http://localhost:18060` puis `http://host.docker.internal:18060`, ou utilisez `XIAOHONGSHU_API_BASE` pour une URL personnalisée | Aucune clé API last30days ; dépend de votre service local de session de navigateur || DripStack (newsletters financières premium) | Sur activation : `--search dripstack` pour une exécution, ou `INCLUDE_SOURCES=dripstack` dans `.env` | Aucune clé ; API de recherche publique et gratuite |-| Perplexity Sonar / Search API / Deep Research | Une clé Perplexity, ou une clé OpenRouter en repli pour Sonar | Paiement à l'usage |+| Perplexity Agent API / Search API / Deep Research | Une clé Perplexity, ou une clé OpenRouter en repli pour Sonar | Paiement à l'usage ; une clé directe active l’Agent API et Deep Research en arrière-plan || Recherche web | Une clé Brave Search | 2 000 requêtes gratuites par mois |### Trousseau macOS (facultatif)diff --git a/README.ja.md b/README.ja.mdindex f6516acb..696b3429 100644--- a/README.ja.md+++ b/README.ja.md@@ -81,7 +81,7 @@ CEOと会うとして、直近30日間のツイートと YouTube の文字起こ| **Pinterest** | ビジュアル起点の発見。プロダクトやアイデアに対するピン・保存・コメント。 || **Xiaohongshu(RED)** | 中国のライフスタイル・プロダクト・クリエイターのシグナル。ログイン済みの x-mcp ブラウザプラグイン、または `xiaohongshu-mcp` サービスがローカルで動いているときに、`--search xhs` で明示的に指定して使います。 || **Bluesky** | 分散型のソーシャル層。Twitter 以後の移住で生まれた AT Protocol の投稿です。 |-| **Perplexity** | 根拠付きの Sonar による統合、Search API の生の結果、そして Deep Research。 |+| **Perplexity** | 制御された Agent API の統合、OpenRouter の Sonar フォールバック、Search API の生の結果、明示的な Deep Research。 || **Web** | 編集記事や、ブログの比較記事。数あるシグナルの1つであって、唯一のものではありません。 |コミュニティが今も情報源を増やし続けています。Truth Social をはじめとするニッチな情報源もすでにエンジンに入っていて、さらに追加予定です。@@ -294,7 +294,7 @@ Reddit(コメント込み)、Hacker News、Polymarket、GitHub はすぐに使| TikTok + Instagram + Threads + Pinterest + LinkedIn + YouTube のコメント | ScrapeCreators のキー | 1万リクエストまで無料、以降は従量課金 || Xiaohongshu(RED) | ログイン済みの x-mcp ブラウザプラグインか `xiaohongshu-mcp` サービスを動かしたうえで、実行ごとに `--search xhs` を付けるか `.env` に `INCLUDE_SOURCES=xiaohongshu` を設定して有効化します。last30days は `http://localhost:18060`、次に `http://host.docker.internal:18060` の順に自動で接続を試し、独自のURLを使う場合は `XIAOHONGSHU_API_BASE` を指定します | last30days 側のAPIキーは不要。ローカルのブラウザセッションのサービス次第です || DripStack(有料の金融ニュースレター) | 任意で有効化: 実行ごとに `--search dripstack`、または `.env` に `INCLUDE_SOURCES=dripstack` | キー不要。無料の公開検索APIを使います |-| Perplexity Sonar / Search API / Deep Research | Perplexity のキー、または Sonar の代替として OpenRouter のキー | 従量課金 |+| Perplexity Agent API / Search API / Deep Research | Perplexity のキー、または Sonar の代替として OpenRouter のキー | 従量課金。直接キーで Agent API とバックグラウンド Deep Research が有効になります || ウェブ検索 | Brave Search のキー | 月2,000クエリまで無料 |### macOS のキーチェーン(任意)diff --git a/README.md b/README.mdindex b2e656a5..25410cfc 100644--- a/README.md+++ b/README.md@@ -81,7 +81,7 @@ If you're meeting with a CEO, have you read all their tweets and YouTube transcr| **Pinterest** | Visual discovery. Pins, saves, and comments on products and ideas. || **Xiaohongshu (RED)** | Chinese lifestyle, product, and creator signals. Requested explicitly with `--search xhs` when a logged-in x-mcp browser plugin or `xiaohongshu-mcp` service is running locally. || **Bluesky** | The decentralized social layer. AT Protocol posts from the post-Twitter migration. |-| **Perplexity** | Grounded Sonar synthesis, raw Search API rows, and Deep Research. |+| **Perplexity** | Controlled Agent API synthesis, OpenRouter Sonar fallback, raw Search API rows, and explicit Deep Research. || **Web** | The editorial coverage, the blog comparisons. One signal of many, not the only one. |Community contributors keep adding more. Truth Social and other niche sources are in the engine with more on the way.@@ -294,7 +294,7 @@ These platforms don't have relationships with each other. X doesn't know what Re| TikTok + Instagram + Threads + Pinterest + LinkedIn + YouTube comments | ScrapeCreators key | 10,000 free calls, then PAYG || Xiaohongshu (RED) | Run a logged-in x-mcp browser plugin or `xiaohongshu-mcp` service and opt in with `--search xhs` per run or `INCLUDE_SOURCES=xiaohongshu` in `.env`; last30days auto-probes `http://localhost:18060` then `http://host.docker.internal:18060`, or use `XIAOHONGSHU_API_BASE` for a custom URL | No last30days API key; depends on your local browser-session service || DripStack (premium financial newsletters) | Opt-in: `--search dripstack` per run, or `INCLUDE_SOURCES=dripstack` in `.env` | No key; free public search API |-| Perplexity Sonar / Search API / Deep Research | Perplexity key, or OpenRouter key as Sonar fallback | Pay as you go |+| Perplexity Agent API / Search API / Deep Research | Perplexity key, or OpenRouter key as Sonar fallback | Pay as you go; a direct key enables Agent API and background Deep Research || Web search | Brave Search key | 2,000 free queries/month |### macOS Keychain (optional)diff --git a/README.pt-BR.md b/README.pt-BR.mdindex 7a79fceb..344ea594 100644--- a/README.pt-BR.md+++ b/README.pt-BR.md@@ -81,7 +81,7 @@ Se você vai se reunir com um CEO, já leu todos os tweets e todas as transcriç| **Pinterest** | Descoberta visual. Pins, itens salvos e comentários sobre produtos e ideias. || **Xiaohongshu (RED)** | Sinais chineses sobre estilo de vida, produtos e criadores. É pedido explicitamente com `--search xhs` quando há um plugin de navegador x-mcp logado ou um serviço `xiaohongshu-mcp` rodando localmente. || **Bluesky** | A camada social descentralizada. Publicações do AT Protocol vindas da migração pós-Twitter. |-| **Perplexity** | A síntese fundamentada do Sonar, os resultados brutos da Search API e o Deep Research. |+| **Perplexity** | Síntese controlada da Agent API, alternativa Sonar via OpenRouter, resultados brutos da Search API e Deep Research explícito. || **Web** | A cobertura editorial, as comparações de blog. Um sinal entre muitos, não o único. |A comunidade não para de acrescentar fontes. Truth Social e outras fontes de nicho já estão no motor, e vêm mais por aí.@@ -295,7 +295,7 @@ Essas plataformas não têm relação nenhuma entre si. O X não sabe o que o Re| TikTok + Instagram + Threads + Pinterest + LinkedIn + comentários do YouTube | Uma chave do ScrapeCreators | 10.000 chamadas gratuitas e depois pagamento por uso || Xiaohongshu (RED) | Deixe rodando um plugin de navegador x-mcp logado ou um serviço `xiaohongshu-mcp` e habilite a fonte com `--search xhs` por execução ou com `INCLUDE_SOURCES=xiaohongshu` no `.env`; o last30days testa automaticamente `http://localhost:18060` e depois `http://host.docker.internal:18060`, ou use `XIAOHONGSHU_API_BASE` para uma URL própria | Não precisa de chave de API do last30days; depende do seu serviço local de sessão de navegador || DripStack (newsletters financeiras premium) | Opcional: `--search dripstack` por execução, ou `INCLUDE_SOURCES=dripstack` no `.env` | Sem chave; API de busca pública e gratuita |-| Perplexity Sonar / Search API / Deep Research | Uma chave do Perplexity, ou uma chave do OpenRouter como alternativa para o Sonar | Pagamento por uso |+| Perplexity Agent API / Search API / Deep Research | Uma chave do Perplexity, ou uma chave do OpenRouter como alternativa para o Sonar | Pagamento por uso; uma chave direta ativa a Agent API e o Deep Research em segundo plano || Busca na web | Uma chave do Brave Search | 2.000 consultas gratuitas por mês |### Keychain do macOS (opcional)diff --git a/README.zh-CN.md b/README.zh-CN.mdindex d8010894..a1e98b07 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -84,7 +84,7 @@ Google 聚合编辑选出的内容,`/last30days` 搜索真实的人。| **Pinterest** | 视觉发现:围绕产品和创意的 Pin、收藏与评论。 || **小红书(RED)** | 来自中国生活方式、产品和创作者的信号。当本机运行已登录的 x-mcp 浏览器插件或 `xiaohongshu-mcp` 服务时,通过 `--search xhs` 显式启用。 || **Bluesky** | 去中心化的社交内容层,搜索 Twitter 用户迁移后产生的 AT Protocol 帖子。 |-| **Perplexity** | 基于来源的 Sonar 综合结果、原始 Search API 数据和 Deep Research。 |+| **Perplexity** | 受控 Agent API 综合结果、OpenRouter Sonar 回退、原始 Search API 数据和显式 Deep Research。 || **Web** | 编辑报道和博客对比。它只是众多信号之一,而不是唯一来源。 |社区贡献者仍在不断加入更多平台。Truth Social 等垂直来源已经进入引擎,更多来源也在路上。@@ -293,7 +293,7 @@ Reddit(含评论)、Hacker News、Polymarket 和 GitHub 无需任何配置| TikTok + Instagram + Threads + Pinterest + LinkedIn + YouTube 评论 | ScrapeCreators 密钥 | 前 10,000 次调用免费,之后按量付费 || 小红书(RED) | 运行已登录的 x-mcp 浏览器插件或 `xiaohongshu-mcp` 服务,并在单次运行中通过 `--search xhs` 启用,或在 `.env` 中设置 `INCLUDE_SOURCES=xiaohongshu`;last30days 会依次自动探测 `http://localhost:18060` 和 `http://host.docker.internal:18060`,也可通过 `XIAOHONGSHU_API_BASE` 指定自定义地址 | last30days 不需要 API 密钥;依赖本地浏览器会话服务 || DripStack(付费金融通讯) | 每次运行通过 `--search dripstack` 启用,或在 `.env` 中设置 `INCLUDE_SOURCES=dripstack` | 无需密钥;公共搜索 API 免费 |-| Perplexity Sonar / Search API / Deep Research | Perplexity 密钥,或作为 Sonar 回退方案的 OpenRouter 密钥 | 按量付费 |+| Perplexity Agent API / Search API / Deep Research | Perplexity 密钥,或作为 Sonar 回退方案的 OpenRouter 密钥 | 按量付费;直接密钥启用 Agent API 和后台 Deep Research || Web 搜索 | Brave Search 密钥 | 每月 2,000 次免费查询 |### macOS Keychain(可选)diff --git a/changelog.d/+perplexity-agent-api.changed.md b/changelog.d/+perplexity-agent-api.changed.mdnew file mode 100644index 00000000..5c0eee55--- /dev/null+++ b/changelog.d/+perplexity-agent-api.changed.md@@ -0,0 +1 @@+Direct Perplexity keys now use the Agent API for controlled synthesis and explicit Deep Research. Controlled synthesis forces grounded web search and supports explicit Anthropic Agent models with a bounded output budget, while Deep Research starts at most one paid background run per command and preserves safe polling and incomplete-run receipts. Existing OpenRouter-only installs keep the synchronous Sonar and Sonar Deep Research fallbacks.diff --git a/skills/last30days/SKILL.md b/skills/last30days/SKILL.mdindex 3040fbc8..8075423a 100644--- a/skills/last30days/SKILL.md+++ b/skills/last30days/SKILL.md@@ -702,7 +702,7 @@ The magic of /last30days is Reddit comments + X posts together - and both are fr- After adding your key, set `INCLUDE_SOURCES=tiktok,instagram` to turn on the popular ones. (Threads, Pinterest, and LinkedIn are also available via `INCLUDE_SOURCES=threads,pinterest,linkedin` for power users.)**Other optional sources (add anytime):**-- `PERPLEXITY_API_KEY=xxx` (or `OPENROUTER_API_KEY=xxx`) - AI-synthesized research with citations; set `INCLUDE_SOURCES=perplexity`.+- `PERPLEXITY_API_KEY=xxx` - preferred Agent/Search API path with citations; set `INCLUDE_SOURCES=perplexity`. Existing `OPENROUTER_API_KEY` installs keep the synchronous Sonar fallback.- `XIAOHONGSHU_API_BASE=http://localhost:18060` - Xiaohongshu/RED via a logged-in x-mcp browser plugin or `xiaohongshu-mcp` service; optional unless the local service runs on a custom URL. Opt in per run with `--search xhs`, or persistently via `INCLUDE_SOURCES=xiaohongshu`.- DripStack (premium financial newsletter search) is opt-in only: per run with `--search dripstack`, or persistently via `INCLUDE_SOURCES=dripstack`. Free public search API, no key; never active without the opt-in.- `BSKY_HANDLE=you.bsky.social` + `BSKY_APP_PASSWORD=xxx` - Bluesky (free app password).@@ -767,7 +767,7 @@ SKILL_DIR="<absolute path of the directory containing the SKILL.md you just Read**Local corpus source:** If the user asks to include their own notes/documents, preserve each supplied directory as a repeatable `--corpus <dir>` engine flag. `LAST30DAYS_CORPUS_DIRS` activates persistent registered directories automatically. Do not WebSearch, upload, quote into a hosted request, or otherwise expose those paths or contents. Corpus retrieval is an offline source lane; its candidates also bypass remote reranker/fun-scoring prompts and use deterministic local scoring. The engine renders matches under the 🔒 **From your files** badge. The normal recency window uses file modification time; add `--corpus-all-time` only when the user explicitly asks to include older files. Corpus evidence is excluded from `--publish-html`, `library feed --publish`, and agent JSON by default. `LAST30DAYS_CORPUS_IN_EXPORT=1` is the explicit agent-JSON privacy opt-in; never enable it on the user's behalf. When a corpus is configured alongside `LAST30DAYS_API_KEY`/`LAST30DAYS_API_BASE`, the engine deliberately bypasses the hosted backend and runs locally.-**Perplexity source:** use it only when the user asks for Perplexity, Deep Research, or paid grounded synthesis, or when `perplexity` is already enabled in `INCLUDE_SOURCES` / `--search`. Direct `PERPLEXITY_API_KEY` supports Sonar synthesis, Search API rows, and async Deep Research. `OPENROUTER_API_KEY` is only a Sonar fallback. Normal runs default to `LAST30DAYS_PERPLEXITY_MODE=sonar`; use `search` for raw ranked web rows, `both` for synthesis plus rows, and `--deep-research` for `sonar-deep-research` with a 600s default wall timeout. A local Deep Research timeout is not a failed API key; inspect the raw artifact's async request id/status and resume by id if needed.+**Perplexity source:** use it only when the user asks for Perplexity, Deep Research, or paid grounded synthesis, or when `perplexity` is already enabled in `INCLUDE_SOURCES` / `--search`. Prefer `PERPLEXITY_API_KEY`: normal runs use the controlled Agent API path, `search` returns raw Search API rows, and `both` combines them. Existing `OPENROUTER_API_KEY` installs stay compatible through one synchronous Sonar call; `search` and `both` fall back to Sonar because those direct APIs need a Perplexity key. Every normal mode is capped at one whole-topic planner subquery per command, including competitor fanout, and is not repeated during thin-source retries. With a direct key, normal Agent mode supplies only `web_search`, forces it for citation-critical grounding, uses a bounded step count, and supplies a local instruction. `sonar` remains a deprecated direct-key alias for `agent`. `LAST30DAYS_PERPLEXITY_AGENT_PRESET` is an explicit direct-key choice only; never set it for the user. `--deep-research` requires a normal positional topic. A direct key starts at most one paid `high`-preset background run with a 600-second default wall timeout; OpenRouter preserves the synchronous `perplexity/sonar-deep-research` fallback. It cannot be combined with discovery, drill, cached-only, competitor, or vs-mode. A local timeout does not stop a direct remote run. Report safe model and response metadata, but never expose request headers or raw tool traces.**Reddit backend pin:** Reddit defaults to the free keyless backend. When `SCRAPECREATORS_API_KEY` is available, ScrapeCreators Reddit **search** backfills only if that free path returns **no items** (empty-only — a thin but non-empty free scrape does not spend credits). If the user wants paid coverage on thin free runs, tell them to set `LAST30DAYS_REDDIT_SC_MIN_ITEMS=<N>` (backfill when free yield is below N). If they say public Reddit is shallow, bot-gated, or missing nested comments, tell them they can set `LAST30DAYS_REDDIT_BACKEND=scrapecreators` alongside `SCRAPECREATORS_API_KEY` to make ScrapeCreators primary and keep the free path as fallback. Do not set either automatically for normal runs.diff --git a/skills/last30days/scripts/last30days.py b/skills/last30days/scripts/last30days.pyindex e544cd16..12f80f60 100644--- a/skills/last30days/scripts/last30days.py+++ b/skills/last30days/scripts/last30days.py@@ -119,6 +119,42 @@ def resolve_requested_sources(args_search: str | None, config: dict) -> list[strreturn None+def add_deep_research_source(+ requested_sources: list[str] | None,+) -> list[str] | None:+ """Add Perplexity without replacing the default-source sentinel.++ ``None`` means that the planner can use the normal configured source set.+ Deep Research enables Perplexity through ``INCLUDE_SOURCES`` separately, so+ converting this sentinel to ``["perplexity"]`` would suppress every normal+ source.+ """+ if requested_sources is None:+ return None+ if "perplexity" in requested_sources:+ return requested_sources+ return [*requested_sources, "perplexity"]+++def enable_deep_research_source(config: dict) -> None:+ """Enable the exact Perplexity token or reject a hard exclusion."""+ excluded = {+ token.strip().lower()+ for token in str(config.get("EXCLUDE_SOURCES") or "").split(",")+ if token.strip()+ }+ if "perplexity" in excluded:+ raise ValueError(+ "--deep-research conflicts with EXCLUDE_SOURCES=perplexity"+ )++ include = str(config.get("INCLUDE_SOURCES") or "")+ tokens = [token.strip() for token in include.split(",") if token.strip()]+ if "perplexity" not in {token.lower() for token in tokens}:+ tokens.append("perplexity")+ config["INCLUDE_SOURCES"] = ",".join(tokens)++def plan_has_explicit_trustpilot_domain(comp_plan: dict | None) -> bool:"""True when any --competitors-plan entry pins a trustpilot_domain."""if not comp_plan:@@ -681,7 +717,7 @@ def build_parser() -> argparse.ArgumentParser:help="Web search backend (default: auto, tries Brave then Exa then Serper then Parallel; ""keyless forces the zero-key DuckDuckGo/SearXNG floor)")parser.add_argument("--deep-research", action="store_true",- help="Use Perplexity Deep Research (~$0.90/query) for in-depth analysis. Requires PERPLEXITY_API_KEY or OPENROUTER_API_KEY.")+ help="Use at most one Perplexity Deep Research run. Direct PERPLEXITY_API_KEY uses the Agent API background path; OPENROUTER_API_KEY keeps the synchronous Sonar fallback; cannot be combined with competitor or vs-mode.")parser.add_argument("--hiring-signals", action="store_true",help="Analyze public jobs/careers postings as evidence-backed company focus signals.")parser.add_argument("--plan", help="JSON query plan (skips internal LLM planner). Can be a JSON string or a file path.")@@ -2964,6 +3000,13 @@ def _main(# Bare --discover (no domain) is global trending, so the dispatch keys on# "flag present" (is not None), never on the domain string's truthiness.+ if args.deep_research and not topic:+ sys.stderr.write(+ "[last30days] --deep-research requires a normal positional topic; "+ "it cannot be combined with discovery, drill, or cached-only modes.\n"+ )+ return 2+if args.discover is not None:if topic:sys.stderr.write(@@ -3083,6 +3126,41 @@ def _main(if args.lookback_days is None:args.lookback_days = 30+ if args.deep_research and not args.diagnose:+ from lib import planner as _planner++ if not (+ config.get("PERPLEXITY_API_KEY")+ or config.get("OPENROUTER_API_KEY")+ ):+ print(+ "Error: --deep-research requires PERPLEXITY_API_KEY or "+ "OPENROUTER_API_KEY",+ file=sys.stderr,+ )+ return 1+ comparison_requested = any(+ value is not None+ for value in (+ args.competitors,+ args.competitors_list,+ args.competitors_plan,+ )+ ) or len(_planner._comparison_entities(topic, uncapped=True)) >= 2+ if comparison_requested:+ sys.stderr.write(+ "Error: --deep-research cannot be combined with competitor or vs-mode. "+ "It permits one paid Deep Research run per user action; run each topic "+ "separately.\n"+ )+ return 2+ config["_deep_research"] = True+ try:+ enable_deep_research_source(config)+ except ValueError as exc:+ print(f"Error: {exc}", file=sys.stderr)+ return 2+# Reject a misspelled configured register before remote submission or any# local source retrieval. Excluded modes resolve to default and remain# unaffected by the register setting.@@ -3114,6 +3192,7 @@ def _main(and env.read_secret_env("LAST30DAYS_API_KEY")and os.environ.get("LAST30DAYS_API_BASE")and not resolved_corpus_dirs+ and not args.deep_research):if _freshness_enabled(args, config):if args.verify_freshness is True:@@ -3148,6 +3227,8 @@ def _main(return hosted.run_hosted(topic, depth, **hosted_kwargs)requested_sources = resolve_requested_sources(args.search, config)+ if args.deep_research:+ requested_sources = add_deep_research_source(requested_sources)# Explicit --trustpilot-domain is user intent: activate the opt-in source# before diagnose/run so the flag cannot silently no-op (#873). Auto-resolve# hints are applied later and must not call this path.@@ -3166,6 +3247,11 @@ def _main(print(json.dumps(diag, indent=2, sort_keys=True))return 0+ # Competitor sub-runs shallow-copy this config. The shared object makes the+ # paid Perplexity cap command-wide and thread-safe across that fanout. Keep+ # this runtime-only object out of the safe diagnose configuration contract.+ config["_perplexity_paid_budget"] = pipeline.PaidSourceBudget()+if not topic:parser.print_usage(sys.stderr)return 2@@ -3187,7 +3273,11 @@ def _main(sys.stderr.write(refuse_msg)return 2- if args.emit == "html" and synthesis_md is not None:+ if (+ args.emit == "html"+ and synthesis_md is not None+ and not args.deep_research+ ):cached = _load_last_report_cache(topic,ttl_seconds=_report_cache_ttl_seconds(config),@@ -3356,17 +3446,6 @@ def _main(f"{','.join(original_github_repos)} -> {','.join(github_repos)}\n")- # --deep-research: auto-enable perplexity source and set deep flag- if args.deep_research:- if not (config.get("PERPLEXITY_API_KEY") or config.get("OPENROUTER_API_KEY")):- print("Error: --deep-research requires PERPLEXITY_API_KEY or OPENROUTER_API_KEY", file=sys.stderr)- sys.exit(1)- config["_deep_research"] = True- # Auto-enable perplexity in INCLUDE_SOURCES- include = config.get("INCLUDE_SOURCES") or ""- if "perplexity" not in include.lower():- config["INCLUDE_SOURCES"] = f"{include},perplexity" if include else "perplexity"-# Polymarket disambiguation: if user passed --polymarket-keywords,# store on config so the polymarket adapter can filter matches.if args.polymarket_keywords:@@ -3410,6 +3489,10 @@ def _main(comp_explicit=comp_explicit,comp_plan=comp_plan,)+ if comp_enabled:+ config["_perplexity_paid_budget"] = pipeline.PaidSourceBudget(+ owner=topic,+ )# Plan alone with zero peers (empty/invalid JSON object, or all entries# skipped) must not fall through to discover-N with a misleading abort.diff --git a/skills/last30days/scripts/lib/doctor.py b/skills/last30days/scripts/lib/doctor.pyindex 19c71156..6e255d53 100644--- a/skills/last30days/scripts/lib/doctor.py+++ b/skills/last30days/scripts/lib/doctor.py@@ -687,8 +687,13 @@ def _truthsocial_record(config):def _perplexity_record(config):- requires = "PERPLEXITY_API_KEY or OPENROUTER_API_KEY + INCLUDE_SOURCES=perplexity"- has_key = bool(config.get("PERPLEXITY_API_KEY") or config.get("OPENROUTER_API_KEY"))+ requires = (+ "PERPLEXITY_API_KEY or OPENROUTER_API_KEY + "+ "INCLUDE_SOURCES=perplexity"+ )+ has_direct_key = bool(config.get("PERPLEXITY_API_KEY"))+ has_openrouter_key = bool(config.get("OPENROUTER_API_KEY"))+ has_key = has_direct_key or has_openrouter_keyinclude = env.include_sources(config)if not has_key:return _record(@@ -699,7 +704,15 @@ def _perplexity_record(config):),)if "perplexity" in include:- return _record(status=health.OK, requires=requires)+ return _record(+ status=health.OK,+ requires=requires,+ note=(+ "direct Agent/Search APIs"+ if has_direct_key+ else "OpenRouter Sonar compatibility fallback"+ ),+ )return _record(status="opt-in", requires=requires,fix="add perplexity to INCLUDE_SOURCES (or request it via --search perplexity)",diff --git a/skills/last30days/scripts/lib/env.py b/skills/last30days/scripts/lib/env.pyindex dcfa8645..9004ced2 100644--- a/skills/last30days/scripts/lib/env.py+++ b/skills/last30days/scripts/lib/env.py@@ -517,8 +517,15 @@ def get_config(policy: ConfigLoadPolicy | None = None) -> dict[str, Any]:('SERPER_API_KEY', None),('OPENROUTER_API_KEY', None),('PERPLEXITY_API_KEY', None),- ('LAST30DAYS_PERPLEXITY_MODE', 'sonar'),+ ('LAST30DAYS_PERPLEXITY_MODE', 'agent'),+ # Legacy Sonar setting. Retain it during migration so existing env+ # files load, but the Agent adapter does not map it to a dynamic preset.('LAST30DAYS_PERPLEXITY_MODEL', None),+ ('LAST30DAYS_PERPLEXITY_AGENT_MODEL', None),+ ('LAST30DAYS_PERPLEXITY_AGENT_PRESET', None),+ ('LAST30DAYS_PERPLEXITY_AGENT_MAX_STEPS', None),+ ('LAST30DAYS_PERPLEXITY_AGENT_MAX_OUTPUT_TOKENS', None),+ ('LAST30DAYS_PERPLEXITY_AGENT_TIMEOUT_SECONDS', '120'),('LAST30DAYS_PERPLEXITY_MAX_RESULTS', None),('LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE', None),('LAST30DAYS_PERPLEXITY_SEARCH_MODE', None),diff --git a/skills/last30days/scripts/lib/http.py b/skills/last30days/scripts/lib/http.pyindex c0828ab5..7f1e21c0 100644--- a/skills/last30days/scripts/lib/http.py+++ b/skills/last30days/scripts/lib/http.py@@ -417,6 +417,16 @@ class HTTPError(Exception):)+class DeadlineExceeded(HTTPError):+ """The caller's shared wall deadline expired across request retries."""++ def __init__(self):+ super().__init__(+ "Request deadline exceeded",+ outcome_state=health.TIMEOUT,+ )++@contextmanagerdef capture_failures():"""Capture terminal request failures in the current retrieval context.@@ -551,10 +561,11 @@ def request(headers: Optional[Dict[str, str]] = None,json_data: Optional[Dict[str, Any]] = None,params: Optional[Dict[str, Any]] = None,- timeout: int = DEFAULT_TIMEOUT,+ timeout: float = DEFAULT_TIMEOUT,retries: int = MAX_RETRIES,max_429_retries: int = MAX_429_RETRIES,raw: bool = False,+ deadline_monotonic: float | None = None,) -> Union[Dict[str, Any], str]:"""Make an HTTP request and return JSON response.@@ -569,6 +580,8 @@ def request(retries: Number of retries on failuremax_429_retries: Maximum 429 retries before giving up (separate cap)raw: If True, return raw response text instead of parsed JSON+ deadline_monotonic: Optional absolute monotonic deadline shared by all+ attempts and retry delays.Returns:Parsed JSON response as dict, or raw text string if raw=True.@@ -627,17 +640,77 @@ def request(_fixture_record(fixture_request, error=error, redactions=fixture_redactions)_raise(error)+ def deadline_error() -> HTTPError:+ return DeadlineExceeded()++ def sleep_before_retry(delay: float) -> bool:+ """Sleep only when the full delay fits inside the caller's deadline."""+ nonlocal last_error+ if deadline_monotonic is not None:+ remaining = deadline_monotonic - time.monotonic()+ if remaining <= 0 or delay >= remaining:+ last_error = deadline_error()+ return False+ time.sleep(delay)+ return True++ def open_and_read(request_timeout: float) -> tuple[int, str]:+ with urllib.request.urlopen(req, timeout=request_timeout) as response:+ return response.status, response.read().decode('utf-8')++ def open_and_read_before_deadline(+ request_timeout: float,+ ) -> tuple[int, str]:+ """Stop waiting at the wall deadline, even during DNS or body reads."""+ if deadline_monotonic is None:+ return open_and_read(request_timeout)+ remaining = deadline_monotonic - time.monotonic()+ if remaining <= 0:+ raise deadline_error()+ future: Future = Future()++ def worker() -> None:+ try:+ future.set_result(open_and_read(request_timeout))+ except BaseException as exc:+ future.set_exception(exc)++ threading.Thread(target=worker, daemon=True).start()+ try:+ return future.result(timeout=remaining)+ except TimeoutError as exc:+ # A worker-side socket TimeoutError is a transport failure, not+ # proof that the command-wide wall deadline expired. Re-read a+ # completed future so its original exception reaches the normal+ # transport classifier below.+ if future.done():+ return future.result()+ raise deadline_error() from exc+while attempt < effective_retries:+ request_timeout = timeout+ if deadline_monotonic is not None:+ remaining = deadline_monotonic - time.monotonic()+ if remaining <= 0:+ last_error = deadline_error()+ break+ request_timeout = min(timeout, remaining)try:- with urllib.request.urlopen(req, timeout=timeout) as response:- body = response.read().decode('utf-8')- log(f"Response: {response.status} ({len(body)} bytes)")- if raw:- _fixture_record(fixture_request, value=body, redactions=fixture_redactions)- return body- parsed = json.loads(body) if body else {}- _fixture_record(fixture_request, value=parsed, redactions=fixture_redactions)- return parsed+ response_status, body = open_and_read_before_deadline(request_timeout)+ if (+ deadline_monotonic is not None+ and time.monotonic() >= deadline_monotonic+ ):+ raise_recorded(deadline_error())+ log(f"Response: {response_status} ({len(body)} bytes)")+ if raw:+ _fixture_record(fixture_request, value=body, redactions=fixture_redactions)+ return body+ parsed = json.loads(body) if body else {}+ _fixture_record(fixture_request, value=parsed, redactions=fixture_redactions)+ return parsed+ except DeadlineExceeded as exc:+ raise_recorded(exc)except urllib.error.HTTPError as e:body = Nonetry:@@ -676,7 +749,8 @@ def request(log(f"Rate limited (429). Waiting {delay:.1f}s before retry {attempt + 2}/{retries}")else:delay = RETRY_DELAY * (2 ** attempt)- time.sleep(delay)+ if not sleep_before_retry(delay):+ breakelse:# Caller's original retry budget exhausted; an earlier DNS# failure may have widened `effective_retries`, but that@@ -712,11 +786,13 @@ def request(f"DNS resolution failure (attempt {dns_attempts}); "f"retrying in {delay:.1f}s")- time.sleep(delay)+ if not sleep_before_retry(delay):+ breakelif attempt < retries - 1:# Non-DNS URLError (e.g. ConnectionRefused) respects the# caller's original retry budget, not the DNS-widened bound.- time.sleep(RETRY_DELAY * (attempt + 1))+ if not sleep_before_retry(RETRY_DELAY * (attempt + 1)):+ breakelse:# Caller's original retry budget exhausted; an earlier DNS# failure widening `effective_retries` does not carry over@@ -739,7 +815,8 @@ def request()if attempt < retries - 1:# Socket errors respect the caller's original retry budget.- time.sleep(RETRY_DELAY * (attempt + 1))+ if not sleep_before_retry(RETRY_DELAY * (attempt + 1)):+ breakelse:# Original budget exhausted; DNS widening doesn't apply here.breakdiff --git a/skills/last30days/scripts/lib/perplexity.py b/skills/last30days/scripts/lib/perplexity.pyindex ef52b6ce..09383c09 100644--- a/skills/last30days/scripts/lib/perplexity.py+++ b/skills/last30days/scripts/lib/perplexity.py@@ -1,135 +1,101 @@-"""Perplexity Sonar, Search API, and Deep Research.+"""Perplexity Agent API, Search API, and OpenRouter compatibility integration.-Direct Perplexity keys are preferred so the source can use first-party Search-API results and async Deep Research. OpenRouter remains a Sonar compatibility-fallback when no direct Perplexity key is configured.+The Perplexity source is paid and opt-in. A direct key uses a controlled Agent+API request with only web search enabled. Direct Deep Research uses an Agent+API background run with the dynamic high preset. When no direct Perplexity key+exists, OpenRouter preserves the legacy synchronous Sonar fallback."""from __future__ import annotations-import hashlib-import json-import random-import sysimport timefrom datetime import datetime+from typing import Anyfrom urllib.parse import urlparse-from . import http, log+from . import health, http, logOPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions"-PERPLEXITY_URL = "https://api.perplexity.ai/v1/sonar"+PERPLEXITY_AGENT_URL = "https://api.perplexity.ai/v1/agent"PERPLEXITY_SEARCH_URL = "https://api.perplexity.ai/search"-PERPLEXITY_ASYNC_URL = "https://api.perplexity.ai/v1/async/sonar"-OPENROUTER_MODEL_SONAR_PRO = "perplexity/sonar-pro"-OPENROUTER_MODEL_DEEP_RESEARCH = "perplexity/sonar-deep-research"-PERPLEXITY_MODEL_SONAR = "sonar"-PERPLEXITY_MODEL_SONAR_PRO = "sonar-pro"-PERPLEXITY_MODEL_REASONING_PRO = "sonar-reasoning-pro"-PERPLEXITY_MODEL_DEEP_RESEARCH = "sonar-deep-research"-PERPLEXITY_MODE_SONAR = "sonar"+PERPLEXITY_MODE_AGENT = "agent"+PERPLEXITY_MODE_SONAR = "sonar" # Direct-key alias and OpenRouter artifact mode.PERPLEXITY_MODE_SEARCH = "search"PERPLEXITY_MODE_BOTH = "both"+PERPLEXITY_DEFAULT_AGENT_TIMEOUT_SECONDS = 120PERPLEXITY_DEFAULT_DEEP_TIMEOUT_SECONDS = 600PERPLEXITY_DEEP_INITIAL_POLL_DELAY_SECONDS = 5.0PERPLEXITY_DEEP_MAX_POLL_DELAY_SECONDS = 60.0-DIRECT_MODELS = {- PERPLEXITY_MODEL_SONAR,- PERPLEXITY_MODEL_SONAR_PRO,- PERPLEXITY_MODEL_REASONING_PRO,- PERPLEXITY_MODEL_DEEP_RESEARCH,-}+PERPLEXITY_DEFAULT_AGENT_MODEL = "perplexity/sonar"+OPENROUTER_MODEL_SONAR_PRO = "perplexity/sonar-pro"+OPENROUTER_MODEL_DEEP_RESEARCH = "perplexity/sonar-deep-research"+PERPLEXITY_DEFAULT_ANTHROPIC_MAX_OUTPUT_TOKENS = 4096+PERPLEXITY_CONTROLLED_PROFILE = "last30days-controlled-web-search/v1"+PERPLEXITY_PRESET_PROFILE = "perplexity-agent-preset"+AGENT_PRESETS = {"fast", "low", "medium", "high"}DIRECT_MODES = {- PERPLEXITY_MODE_SONAR,+ PERPLEXITY_MODE_AGENT,PERPLEXITY_MODE_SEARCH,PERPLEXITY_MODE_BOTH,}SEARCH_CONTEXT_SIZES = {"low", "medium", "high"}SEARCH_RECENCY_FILTERS = {"hour", "day", "week", "month", "year"}-SONAR_SEARCH_MODES = {"web", "academic", "sec"}REASONING_EFFORTS = {"minimal", "low", "medium", "high"}+CONTROLLED_AGENT_INSTRUCTIONS = (+ "Use the supplied web search tool for current, source-grounded research. "+ "Keep the answer concise. Cite source-backed claims in the answer. "+ "Do not use tools other than those supplied in this request."+)+-class AsyncDeepResearchTimeout(TimeoutError):- def __init__(self, metadata: dict):- timeout_seconds = metadata.get("asyncTimeoutSeconds") or "unknown"- super().__init__(f"Async Deep Research exceeded {timeout_seconds}s wall timeout")+class AgentBackgroundTimeout(TimeoutError):+ def __init__(self, metadata: dict[str, Any]):+ timeout_seconds = metadata.get("backgroundTimeoutSeconds") or "unknown"+ super().__init__(f"Agent background run exceeded {timeout_seconds}s wall timeout")self.metadata = metadata-class AsyncDeepResearchFailed(RuntimeError):- def __init__(self, metadata: dict):- message = metadata.get("asyncErrorMessage") or "Async Deep Research failed"- super().__init__(str(message))+class AgentBackgroundFailed(RuntimeError):+ def __init__(self, metadata: dict[str, Any]):+ detail = metadata.get("backgroundErrorMessage") or "Agent background run failed"+ super().__init__(str(detail))self.metadata = metadata-class AsyncDeepResearchPollError(RuntimeError):- def __init__(self, metadata: dict):- message = metadata.get("asyncPollError") or "Async Deep Research poll failed"- super().__init__(str(message))+class AgentBackgroundPollError(RuntimeError):+ def __init__(self, metadata: dict[str, Any]):+ detail = metadata.get("backgroundPollError") or "Agent background poll failed"+ super().__init__(str(detail))self.metadata = metadata-def _log(msg: str):- log.source_log("Perplexity", msg, tty_only=False)+def _log(message: str) -> None:+ log.source_log("Perplexity", message, tty_only=False)def _domain(url: str) -> str:return urlparse(url).netloc.strip().lower()-def _provider(config: dict, deep: bool) -> tuple[str, str, str, str] | None:- """Return (provider, api_key, url, model), preferring direct Perplexity."""- if config.get("PERPLEXITY_API_KEY"):- model = _direct_model(config, deep)- url = PERPLEXITY_ASYNC_URL if deep else PERPLEXITY_URL- return "perplexity", config["PERPLEXITY_API_KEY"], url, model- if config.get("OPENROUTER_API_KEY"):- model = OPENROUTER_MODEL_DEEP_RESEARCH if deep else OPENROUTER_MODEL_SONAR_PRO- return "openrouter", config["OPENROUTER_API_KEY"], OPENROUTER_URL, model- return None---def _config_text(config: dict, key: str) -> str:+def _config_text(config: dict[str, Any], key: str) -> str:return str(config.get(key) or "").strip()def _csv_values(raw: str, limit: int | None = None) -> list[str]:values = [part.strip() for part in raw.split(",") if part.strip()]- # values[:None] already returns the whole list, so no None guard is needed.return values[:limit]-def _direct_model(config: dict, deep: bool) -> str:- if deep:- return PERPLEXITY_MODEL_DEEP_RESEARCH- model = _config_text(config, "LAST30DAYS_PERPLEXITY_MODEL") or PERPLEXITY_MODEL_SONAR_PRO- if model not in DIRECT_MODELS:- _log(f"Unsupported LAST30DAYS_PERPLEXITY_MODEL={model!r}; using sonar-pro")- return PERPLEXITY_MODEL_SONAR_PRO- if model == PERPLEXITY_MODEL_DEEP_RESEARCH:- return PERPLEXITY_MODEL_SONAR_PRO- return model---def _mode(config: dict, provider: str, deep: bool) -> str:- if deep:- return PERPLEXITY_MODE_SONAR- mode = (_config_text(config, "LAST30DAYS_PERPLEXITY_MODE") or PERPLEXITY_MODE_SONAR).lower()- if mode not in DIRECT_MODES:- _log(f"Unsupported LAST30DAYS_PERPLEXITY_MODE={mode!r}; using sonar")- return PERPLEXITY_MODE_SONAR- if provider != "perplexity" and mode != PERPLEXITY_MODE_SONAR:- _log("Search API modes require PERPLEXITY_API_KEY; using OpenRouter Sonar fallback")- return PERPLEXITY_MODE_SONAR- return mode---def _positive_int(raw: object, default: int, min_value: int, max_value: int | None = None) -> int:+def _positive_int(+ raw: object,+ default: int,+ min_value: int,+ max_value: int | None = None,+) -> int:try:value = int(str(raw).strip())except (TypeError, ValueError):@@ -149,44 +115,13 @@ def _mmddyyyy(date: str | None) -> str | None:return None-def _usage(data: dict) -> dict:+def _usage(data: dict[str, Any]) -> dict[str, Any]:usage = data.get("usage")return usage if isinstance(usage, dict) else {}-def _idempotency_key(json_data: dict) -> str:- payload = json.dumps(json_data, sort_keys=True, separators=(",", ":"))- digest = hashlib.sha256(payload.encode("utf-8")).hexdigest()[:32]- return f"last30days:{digest}"---def _async_metadata(- data: dict,- request_id: str,- timeout_seconds: int,- idempotency_key: str,- poll_count: int,- local_status: str,-) -> dict:- metadata = {- "async": True,- "asyncRequestId": request_id,- "asyncStatus": data.get("status"),- "asyncTimeoutSeconds": timeout_seconds,- "asyncIdempotencyKey": idempotency_key,- "asyncPollCount": poll_count,- "asyncLocalStatus": local_status,- "asyncCreatedAt": data.get("created_at"),- "asyncStartedAt": data.get("started_at"),- "asyncCompletedAt": data.get("completed_at"),- "asyncFailedAt": data.get("failed_at"),- "asyncErrorMessage": data.get("error_message"),- }- return {k: v for k, v in metadata.items() if v is not None}---def _error_artifact(exc: Exception) -> dict:- artifact = {+def _error_artifact(exc: Exception) -> dict[str, Any]:+ artifact: dict[str, Any] = {"error": type(exc).__name__,"message": str(exc)[:200],}@@ -195,86 +130,127 @@ def _error_artifact(exc: Exception) -> dict:return artifact-def _empty_async_sonar_artifact(- provider: str,- model: str,- deep: bool,- query: str,- data: dict,- async_artifact: dict,- error: str,- message: str,-) -> dict:- if not async_artifact:- return {}- artifact = {- "label": "perplexity",- "provider": provider,- "mode": PERPLEXITY_MODE_SONAR,- "endpoint": "async-sonar",- "model": model,- "deep": deep,- "query": query,- "error": error,- "synthesisLength": 0,- "citationCount": 0,- "usage": _usage(data),- **async_artifact,- }- if not artifact.get("asyncErrorMessage"):- artifact["asyncErrorMessage"] = message- return artifact+def _provider(config: dict[str, Any]) -> tuple[str, str] | None:+ """Prefer direct Perplexity, then preserve the OpenRouter Sonar fallback."""+ api_key = _config_text(config, "PERPLEXITY_API_KEY")+ if api_key:+ return "perplexity", api_key+ openrouter_key = _config_text(config, "OPENROUTER_API_KEY")+ if openrouter_key:+ return "openrouter", openrouter_key+ return None-def _build_sonar_payload(prompt: str, model: str, date_range: tuple[str, str], config: dict) -> dict:- payload = {- "model": model,- "messages": [{"role": "user", "content": prompt}],- }+def _mode(config: dict[str, Any], deep: bool, provider: str) -> str:+ if deep:+ return (+ PERPLEXITY_MODE_AGENT+ if provider == "perplexity"+ else PERPLEXITY_MODE_SONAR+ )- from_date, to_date = date_range- web_options: dict[str, object] = {}- search_mode = _config_text(config, "LAST30DAYS_PERPLEXITY_SEARCH_MODE").lower()- if search_mode in SONAR_SEARCH_MODES:- web_options["search_mode"] = search_mode+ mode = (+ _config_text(config, "LAST30DAYS_PERPLEXITY_MODE")+ or PERPLEXITY_MODE_AGENT+ ).lower()+ if provider == "openrouter":+ if mode in {PERPLEXITY_MODE_SEARCH, PERPLEXITY_MODE_BOTH}:+ _log(+ f"LAST30DAYS_PERPLEXITY_MODE={mode} requires PERPLEXITY_API_KEY; "+ "using the OpenRouter Sonar fallback"+ )+ return PERPLEXITY_MODE_SONAR+ if mode == PERPLEXITY_MODE_SONAR:+ _log(+ "LAST30DAYS_PERPLEXITY_MODE=sonar is deprecated; "+ "using the Agent API controlled profile"+ )+ return PERPLEXITY_MODE_AGENT+ if mode not in DIRECT_MODES:+ _log(f"Unsupported LAST30DAYS_PERPLEXITY_MODE={mode!r}; using agent")+ return PERPLEXITY_MODE_AGENT+ return mode- domains = _csv_values(_config_text(config, "LAST30DAYS_PERPLEXITY_DOMAIN_FILTER"), limit=20)- if domains:- web_options["search_domain_filter"] = domains- languages = _csv_values(_config_text(config, "LAST30DAYS_PERPLEXITY_LANGUAGE_FILTER"), limit=20)- if languages:- web_options["search_language_filter"] = languages+def _agent_preset(config: dict[str, Any], deep: bool) -> str | None:+ if deep:+ return "high"- recency = _config_text(config, "LAST30DAYS_PERPLEXITY_RECENCY_FILTER").lower()- if recency in SEARCH_RECENCY_FILTERS:- web_options["search_recency_filter"] = recency+ preset = _config_text(config, "LAST30DAYS_PERPLEXITY_AGENT_PRESET").lower()+ if not preset:+ return None+ if preset in AGENT_PRESETS:+ return preset+ _log(+ "Unsupported LAST30DAYS_PERPLEXITY_AGENT_PRESET="+ f"{preset!r}; using the controlled profile"+ )+ return None- after = _mmddyyyy(from_date)- before = _mmddyyyy(to_date)- if after:- web_options["search_after_date_filter"] = after- if before:- web_options["search_before_date_filter"] = before- if web_options:- payload["web_search_options"] = web_options+def _agent_model(config: dict[str, Any]) -> str:+ legacy_model = _config_text(config, "LAST30DAYS_PERPLEXITY_MODEL")+ if legacy_model:+ _log(+ "LAST30DAYS_PERPLEXITY_MODEL is a legacy Sonar setting and is "+ "ignored by the Agent API; set LAST30DAYS_PERPLEXITY_AGENT_MODEL "+ "for an explicit Agent model"+ )+ return (+ _config_text(config, "LAST30DAYS_PERPLEXITY_AGENT_MODEL")+ or PERPLEXITY_DEFAULT_AGENT_MODEL+ )- effort = _config_text(config, "LAST30DAYS_PERPLEXITY_REASONING_EFFORT").lower()- if effort in REASONING_EFFORTS:- payload["reasoning_effort"] = effort- return payload+def _agent_timeout(config: dict[str, Any]) -> int:+ return _positive_int(+ config.get("LAST30DAYS_PERPLEXITY_AGENT_TIMEOUT_SECONDS"),+ PERPLEXITY_DEFAULT_AGENT_TIMEOUT_SECONDS,+ 1,+ 600,+ )+++def _safe_error_message(data: dict[str, Any]) -> str | None:+ error = data.get("error")+ if isinstance(error, str):+ return error[:200]+ if isinstance(error, dict):+ for key in ("message", "detail", "code"):+ value = error.get(key)+ if isinstance(value, str) and value:+ return value[:200]+ return None+++def _safe_incomplete_reason(data: dict[str, Any]) -> str | None:+ details = data.get("incomplete_details")+ if not isinstance(details, dict):+ return None+ reason = details.get("reason")+ return reason[:100] if isinstance(reason, str) and reason else None-def _build_search_payload(query: str, date_range: tuple[str, str], config: dict) -> dict:+def _build_search_payload(+ query: str,+ date_range: tuple[str, str],+ config: dict[str, Any],+) -> dict[str, Any]:from_date, to_date = date_range- payload: dict[str, object] = {+ payload: dict[str, Any] = {"query": query,- "max_results": _positive_int(config.get("LAST30DAYS_PERPLEXITY_MAX_RESULTS"), 10, 1, 20),+ "max_results": _positive_int(+ config.get("LAST30DAYS_PERPLEXITY_MAX_RESULTS"),+ 10,+ 1,+ 20,+ ),}- context_size = _config_text(config, "LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE").lower()+ context_size = _config_text(+ config,+ "LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE",+ ).lower()if context_size in SEARCH_CONTEXT_SIZES:payload["search_context_size"] = context_size@@ -282,11 +258,17 @@ def _build_search_payload(query: str, date_range: tuple[str, str], config: dict)if len(country) == 2:payload["country"] = country- domains = _csv_values(_config_text(config, "LAST30DAYS_PERPLEXITY_DOMAIN_FILTER"), limit=20)+ domains = _csv_values(+ _config_text(config, "LAST30DAYS_PERPLEXITY_DOMAIN_FILTER"),+ limit=20,+ )if domains:payload["search_domain_filter"] = domains- languages = _csv_values(_config_text(config, "LAST30DAYS_PERPLEXITY_LANGUAGE_FILTER"), limit=20)+ languages = _csv_values(+ _config_text(config, "LAST30DAYS_PERPLEXITY_LANGUAGE_FILTER"),+ limit=20,+ )if languages:payload["search_language_filter"] = languages@@ -298,152 +280,499 @@ def _build_search_payload(query: str, date_range: tuple[str, str], config: dict)payload["search_before_date_filter"] = before# Perplexity Search API rejects search_recency_filter when explicit- # published-date filters are present. last30days already passes an exact- # date range, so prefer that and keep recency only for undated callers.- recency = _config_text(config, "LAST30DAYS_PERPLEXITY_RECENCY_FILTER").lower()+ # published-date filters are present. Preserve the upstream fix.+ recency = _config_text(+ config,+ "LAST30DAYS_PERPLEXITY_RECENCY_FILTER",+ ).lower()if recency in SEARCH_RECENCY_FILTERS and not (after or before):payload["search_recency_filter"] = recencyreturn payload-def _append_citation(citations: list[dict], seen_urls: set[str], citation: dict) -> None:- url = (citation.get("url") or "").strip()- if not url or url in seen_urls:+def _build_web_search_tool(+ date_range: tuple[str, str],+ config: dict[str, Any],+) -> dict[str, Any]:+ from_date, to_date = date_range+ tool: dict[str, Any] = {+ "type": "web_search",+ "max_results": _positive_int(+ config.get("LAST30DAYS_PERPLEXITY_MAX_RESULTS"),+ 10,+ 1,+ 20,+ ),+ }++ context_size = _config_text(+ config,+ "LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE",+ ).lower()+ if context_size in SEARCH_CONTEXT_SIZES:+ tool["search_context_size"] = context_size++ country = _config_text(config, "LAST30DAYS_PERPLEXITY_COUNTRY").upper()+ if len(country) == 2:+ tool["user_location"] = {"country": country}++ filters: dict[str, Any] = {}+ domains = _csv_values(+ _config_text(config, "LAST30DAYS_PERPLEXITY_DOMAIN_FILTER"),+ limit=20,+ )+ if domains:+ filters["search_domain_filter"] = domains++ after = _mmddyyyy(from_date)+ before = _mmddyyyy(to_date)+ if after:+ filters["search_after_date_filter"] = after+ if before:+ filters["search_before_date_filter"] = before++ recency = _config_text(+ config,+ "LAST30DAYS_PERPLEXITY_RECENCY_FILTER",+ ).lower()+ if recency in SEARCH_RECENCY_FILTERS and not (after or before):+ filters["search_recency_filter"] = recency+ if filters:+ tool["filters"] = filters++ language_filter = _config_text(+ config,+ "LAST30DAYS_PERPLEXITY_LANGUAGE_FILTER",+ )+ if language_filter:+ _log(+ "LAST30DAYS_PERPLEXITY_LANGUAGE_FILTER has no Agent API "+ "equivalent and applies only to Search API mode"+ )+ search_mode = _config_text(config, "LAST30DAYS_PERPLEXITY_SEARCH_MODE").lower()+ if search_mode and search_mode != "web":+ _log(+ "LAST30DAYS_PERPLEXITY_SEARCH_MODE has no Agent API equivalent; "+ "using web search"+ )++ return tool+++def _safe_request(payload: dict[str, Any]) -> dict[str, Any]:+ request: dict[str, Any] = {}+ for key in (+ "model",+ "preset",+ "max_steps",+ "max_output_tokens",+ "background",+ ):+ if key in payload:+ request[key] = payload[key]+ reasoning = payload.get("reasoning")+ if isinstance(reasoning, dict) and isinstance(reasoning.get("effort"), str):+ request["reasoning"] = {"effort": reasoning["effort"]}+ tool_choice = payload.get("tool_choice")+ if tool_choice == {"type": "web_search"}:+ request["tool_choice"] = tool_choice+ tools = payload.get("tools")+ if isinstance(tools, list):+ request["tools"] = [+ {+ key: tool[key]+ for key in (+ "type",+ "max_results",+ "search_context_size",+ "user_location",+ "filters",+ )+ if key in tool+ }+ for tool in tools+ if isinstance(tool, dict) and tool.get("type") == "web_search"+ ]+ return request+++def _build_agent_payload(+ prompt: str,+ date_range: tuple[str, str],+ config: dict[str, Any],+ deep: bool,+) -> tuple[dict[str, Any], dict[str, Any]]:+ preset = _agent_preset(config, deep)+ if preset:+ payload = {+ "preset": preset,+ "input": prompt,+ # A supplied web_search tool merges with a preset's tools. This+ # preserves the user's date, domain, location, and result bounds+ # without claiming to disable any other dynamic-preset tools.+ "tools": [_build_web_search_tool(date_range, config)],+ }+ if deep:+ payload["background"] = True+ return payload, {+ "profile": PERPLEXITY_PRESET_PROFILE,+ "preset": preset,+ "dynamicPreset": True,+ "request": _safe_request(payload),+ }++ payload: dict[str, Any] = {+ "model": _agent_model(config),+ "instructions": CONTROLLED_AGENT_INSTRUCTIONS,+ "input": prompt,+ "tools": [_build_web_search_tool(date_range, config)],+ "tool_choice": {"type": "web_search"},+ "max_steps": _positive_int(+ config.get("LAST30DAYS_PERPLEXITY_AGENT_MAX_STEPS"),+ 5,+ 1,+ 15,+ ),+ }+ if str(payload["model"]).lower().startswith("anthropic/"):+ payload["max_output_tokens"] = _positive_int(+ config.get("LAST30DAYS_PERPLEXITY_AGENT_MAX_OUTPUT_TOKENS"),+ PERPLEXITY_DEFAULT_ANTHROPIC_MAX_OUTPUT_TOKENS,+ 1,+ 32768,+ )+ effort = _config_text(+ config,+ "LAST30DAYS_PERPLEXITY_REASONING_EFFORT",+ ).lower()+ if effort in REASONING_EFFORTS:+ payload["reasoning"] = {"effort": effort}+ return payload, {+ "profile": PERPLEXITY_CONTROLLED_PROFILE,+ "model": payload["model"],+ "dynamicPreset": False,+ "request": _safe_request(payload),+ }+++def _append_citation(+ citations: list[dict[str, Any]],+ seen_urls: set[str],+ citation: dict[str, Any],+) -> None:+ url = str(citation.get("url") or "").strip()+ if not url:return+ if url in seen_urls:+ # Message annotations commonly carry only a URL and title. Merge the+ # later search_results item instead of discarding its snippet/date.+ for existing in citations:+ if existing.get("url") != url:+ continue+ for key in ("title", "snippet", "date"):+ if not existing.get(key) and citation.get(key):+ existing[key] = citation[key]+ returnseen_urls.add(url)- citations.append({- "url": url,- "title": citation.get("title") or "",- "snippet": citation.get("snippet") or "",- "date": citation.get("date"),- })+ citations.append(+ {+ "url": url,+ "title": citation.get("title") or "",+ "snippet": citation.get("snippet") or "",+ "date": citation.get("date"),+ }+ )+++def _append_annotations(+ citations: list[dict[str, Any]],+ seen_urls: set[str],+ annotations: Any,+) -> None:+ if not isinstance(annotations, list):+ return+ for annotation in annotations:+ if not isinstance(annotation, dict):+ continue+ citation = annotation.get("url_citation")+ if not isinstance(citation, dict):+ citation = annotation+ _append_citation(citations, seen_urls, citation)-def _extract_citations(data: dict, choice: dict) -> list[dict]:- """Extract citations from direct Perplexity and OpenRouter response shapes."""- citations: list[dict] = []+def _extract_agent_citations(data: dict[str, Any]) -> list[dict[str, Any]]:+ citations: list[dict[str, Any]] = []seen_urls: set[str] = set()- search_results_by_url: dict[str, dict] = {}+ for result in data.get("results") or []:+ if isinstance(result, dict):+ _append_citation(citations, seen_urls, result)++ output = data.get("output")+ if not isinstance(output, list):+ return citations++ for item in output:+ if not isinstance(item, dict):+ continue+ item_type = item.get("type")+ if item_type == "search_results":+ for result in item.get("results") or []:+ if isinstance(result, dict):+ _append_citation(citations, seen_urls, result)+ continue+ if item_type != "message":+ continue+ _append_annotations(citations, seen_urls, item.get("annotations"))+ content = item.get("content")+ if not isinstance(content, list):+ continue+ for part in content:+ if isinstance(part, dict):+ _append_annotations(citations, seen_urls, part.get("annotations"))++ return citations+++def _extract_openrouter_citations(+ data: dict[str, Any],+ choice: dict[str, Any],+) -> list[dict[str, Any]]:+ """Read the legacy OpenAI-compatible Sonar citation shapes."""+ citations: list[dict[str, Any]] = []+ seen_urls: set[str] = set()+ search_results: dict[str, dict[str, Any]] = {}for result in data.get("search_results") or []:if not isinstance(result, dict):continue- url = (result.get("url") or "").strip()+ url = str(result.get("url") or "").strip()if not url:continue- search_results_by_url[url] = result+ search_results[url] = result_append_citation(citations, seen_urls, result)for url in data.get("citations") or []:if not isinstance(url, str):continue- result = search_results_by_url.get(url, {})- _append_citation(citations, seen_urls, {- "url": url,- "title": result.get("title") or _domain(url),- "snippet": result.get("snippet") or "",- "date": result.get("date"),- })-- annotations = choice.get("message", {}).get("annotations", [])- for ann in annotations or []:- if not isinstance(ann, dict):- continue- url_citation = ann.get("url_citation", {})- if not isinstance(url_citation, dict):- continue- _append_citation(citations, seen_urls, {- "url": url_citation.get("url") or "",- "title": url_citation.get("title") or "",- })+ result = search_results.get(url, {})+ _append_citation(+ citations,+ seen_urls,+ {+ "url": url,+ "title": result.get("title") or _domain(url),+ "snippet": result.get("snippet") or "",+ "date": result.get("date"),+ },+ )+ message = choice.get("message")+ if isinstance(message, dict):+ _append_annotations(citations, seen_urls, message.get("annotations"))return citations-def _poll_async_sonar(json_data: dict, headers: dict, config: dict) -> tuple[dict, dict]:+def _output_types(data: dict[str, Any]) -> list[str]:+ output = data.get("output")+ if not isinstance(output, list):+ return []+ return [+ item["type"]+ for item in output+ if isinstance(item, dict) and isinstance(item.get("type"), str)+ ]+++def _output_text(data: dict[str, Any]) -> str:+ direct = data.get("output_text")+ if isinstance(direct, str) and direct.strip():+ return direct++ parts: list[str] = []+ output = data.get("output")+ if not isinstance(output, list):+ return ""+ for item in output:+ if not isinstance(item, dict) or item.get("type") != "message":+ continue+ content = item.get("content")+ if isinstance(content, str):+ parts.append(content)+ continue+ if not isinstance(content, list):+ continue+ for part in content:+ if not isinstance(part, dict):+ continue+ if part.get("type") not in {"output_text", "text"}:+ continue+ text = part.get("text")+ if isinstance(text, str):+ parts.append(text)+ return "".join(parts).strip()+++def _background_metadata(+ data: dict[str, Any],+ response_id: str,+ timeout_seconds: int,+ poll_count: int,+ local_status: str,+) -> dict[str, Any]:+ metadata: dict[str, Any] = {+ "background": True,+ "responseId": response_id,+ "backgroundStatus": data.get("status"),+ "servedModel": data.get("model"),+ "usage": _usage(data),+ "outputTypes": _output_types(data),+ "backgroundTimeoutSeconds": timeout_seconds,+ "backgroundPollCount": poll_count,+ "backgroundLocalStatus": local_status,+ }+ message = _safe_error_message(data)+ if message:+ metadata["backgroundErrorMessage"] = message+ incomplete_reason = _safe_incomplete_reason(data)+ if incomplete_reason:+ metadata["incompleteReason"] = incomplete_reason+ return {key: value for key, value in metadata.items() if value is not None}+++def _log_deep_receipt(artifact: dict[str, Any]) -> None:+ """Expose the safe Deep receipt to slash-command and CLI consumers."""+ fields = (+ ("model", artifact.get("servedModel")),+ ("response_id", artifact.get("responseId")),+ ("provider_status", artifact.get("backgroundStatus") or artifact.get("status")),+ ("local_status", artifact.get("backgroundLocalStatus")),+ ("incomplete_reason", artifact.get("incompleteReason")),+ ("polls", artifact.get("backgroundPollCount")),+ ("timeout_seconds", artifact.get("backgroundTimeoutSeconds")),+ )+ rendered = " ".join(+ f"{key}={value}"+ for key, value in fields+ if value is not None+ )+ _log(f"Deep Research receipt: {rendered or 'unavailable'}")+++def _poll_agent_background(+ payload: dict[str, Any],+ headers: dict[str, str],+ config: dict[str, Any],+) -> tuple[dict[str, Any], dict[str, Any]]:timeout_seconds = _positive_int(config.get("LAST30DAYS_PERPLEXITY_DEEP_TIMEOUT_SECONDS"),PERPLEXITY_DEFAULT_DEEP_TIMEOUT_SECONDS,1,None,)- idempotency_key = _idempotency_key(json_data)created = http.post(- PERPLEXITY_ASYNC_URL,- {"request": json_data, "idempotency_key": idempotency_key},+ PERPLEXITY_AGENT_URL,+ payload,headers=headers,timeout=30,- retries=2,+ retries=1,)- request_id = created.get("id")- if not request_id:- raise http.HTTPError("Async Deep Research response missing id")+ response_id = created.get("id")+ if not isinstance(response_id, str) or not response_id:+ raise http.HTTPError("Agent background response missing id")- deadline = time.monotonic() + timeout_seconds- poll_url = f"{PERPLEXITY_ASYNC_URL}/{request_id}"- delay = PERPLEXITY_DEEP_INITIAL_POLL_DELAY_SECONDS- last_status = created.get("status")+ terminal = {"completed", "failed", "cancelled", "incomplete"}+ status = str(created.get("status") or "").lower()+ data = createdpoll_count = 0- last_data = created- if last_status:- _log(f"Deep Research async status: {last_status}")+ if status:+ _log(f"Agent background status: {status}")- while time.monotonic() < deadline:+ deadline = time.monotonic() + timeout_seconds+ delay = PERPLEXITY_DEEP_INITIAL_POLL_DELAY_SECONDS+ while status not in terminal:+ if time.monotonic() >= deadline:+ raise AgentBackgroundTimeout(+ _background_metadata(+ data,+ response_id,+ timeout_seconds,+ poll_count,+ "PENDING_REMOTE",+ )+ )try:- data = http.get(poll_url, headers=headers, timeout=30, retries=2)- except http.HTTPError as e:- metadata = _async_metadata(- last_data, request_id, timeout_seconds, idempotency_key, poll_count + 1,+ data = http.get(+ f"{PERPLEXITY_AGENT_URL}/{response_id}",+ headers=headers,+ timeout=30,+ retries=2,+ deadline_monotonic=deadline,+ )+ except http.HTTPError as exc:+ if isinstance(exc, http.DeadlineExceeded) or time.monotonic() >= deadline:+ raise AgentBackgroundTimeout(+ _background_metadata(+ data,+ response_id,+ timeout_seconds,+ poll_count + 1,+ "PENDING_REMOTE",+ )+ ) from exc+ metadata = _background_metadata(+ data,+ response_id,+ timeout_seconds,+ poll_count + 1,"POLL_ERROR",)- metadata["asyncPollError"] = str(e)- if e.status_code is not None:- metadata["asyncPollStatusCode"] = e.status_code- raise AsyncDeepResearchPollError(metadata)+ metadata["backgroundPollError"] = str(exc)[:200]+ if exc.status_code is not None:+ metadata["backgroundPollStatusCode"] = exc.status_code+ raise AgentBackgroundPollError(metadata) from exc+poll_count += 1- last_data = data- status = data.get("status")- if status and status != last_status:- _log(f"Deep Research async status: {status}")- last_status = status- if status == "COMPLETED":- response = data.get("response")- if not isinstance(response, dict):- metadata = _async_metadata(- data, request_id, timeout_seconds, idempotency_key, poll_count,- "FAILED_REMOTE",- )- metadata["asyncErrorMessage"] = "Async Deep Research completed without response"- raise AsyncDeepResearchFailed(metadata)- return response, _async_metadata(- data, request_id, timeout_seconds, idempotency_key, poll_count,- "COMPLETED_REMOTE",- )- if status == "FAILED":- raise AsyncDeepResearchFailed(_async_metadata(- data, request_id, timeout_seconds, idempotency_key, poll_count,- "FAILED_REMOTE",- ))+ next_status = str(data.get("status") or "").lower()+ if next_status and next_status != status:+ _log(f"Agent background status: {next_status}")+ status = next_statusremaining = deadline - time.monotonic()if remaining <= 0:+ raise AgentBackgroundTimeout(+ _background_metadata(+ data,+ response_id,+ timeout_seconds,+ poll_count,+ "PENDING_REMOTE",+ )+ )+ if status in terminal:break- jitter = random.uniform(0, 2)- time.sleep(min(delay + jitter, max(0.1, remaining)))+ time.sleep(min(delay, remaining))delay = min(delay * 1.5, PERPLEXITY_DEEP_MAX_POLL_DELAY_SECONDS)- raise AsyncDeepResearchTimeout(_async_metadata(- last_data, request_id, timeout_seconds, idempotency_key, poll_count,- "PENDING_REMOTE",- ))+ metadata = _background_metadata(+ data,+ response_id,+ timeout_seconds,+ poll_count,+ "COMPLETED_REMOTE" if status == "completed" else "TERMINAL_REMOTE",+ )+ if status == "completed":+ return data, metadata+ if not status:+ metadata["backgroundErrorMessage"] = "Agent background response has no status"+ raise AgentBackgroundFailed(metadata)def _search_api(query: str,date_range: tuple[str, str],- config: dict,+ config: dict[str, Any],api_key: str,-) -> tuple[list[dict], dict]:+) -> tuple[list[dict[str, Any]], dict[str, Any]]:from_date, to_date = date_rangeheaders = {"Authorization": f"Bearer {api_key}",@@ -452,33 +781,41 @@ def _search_api(payload = _build_search_payload(query, date_range, config)_log(f"Querying Perplexity Search API for '{query}' ({from_date} to {to_date})")- data = http.post(PERPLEXITY_SEARCH_URL, payload, headers=headers, timeout=30)+ data = http.post(+ PERPLEXITY_SEARCH_URL,+ payload,+ headers=headers,+ timeout=30,+ retries=1,+ )results = data.get("results") or []if not isinstance(results, list):results = []- items = []- for i, result in enumerate(results):+ items: list[dict[str, Any]] = []+ for index, result in enumerate(results):if not isinstance(result, dict):continue- url = (result.get("url") or "").strip()+ url = str(result.get("url") or "").strip()if not url:continue- items.append({- "id": f"PXS{i + 1}",- "title": result.get("title") or _domain(url),- "url": url,- "source_domain": _domain(url),- "snippet": result.get("snippet") or "",- "date": result.get("date"),- "relevance": max(0.55, 0.85 - (i * 0.03)),- "why_relevant": f"Ranked by Perplexity Search API for '{query}'",- "engagement": {},- "metadata": {- "last_updated": result.get("last_updated"),- "perplexity_search_id": data.get("id"),- },- })+ items.append(+ {+ "id": f"PXS{index + 1}",+ "title": result.get("title") or _domain(url),+ "url": url,+ "source_domain": _domain(url),+ "snippet": result.get("snippet") or "",+ "date": result.get("date"),+ "relevance": max(0.55, 0.85 - (index * 0.03)),+ "why_relevant": f"Ranked by Perplexity Search API for '{query}'",+ "engagement": {},+ "metadata": {+ "last_updated": result.get("last_updated"),+ "perplexity_search_id": data.get("id"),+ },+ }+ )artifact = {"label": "perplexity",@@ -487,11 +824,7 @@ def _search_api("endpoint": "search","query": query,"resultCount": len(items),- "request": {- k: v- for k, v in payload.items()- if k not in {"query"}- },+ "request": {key: value for key, value in payload.items() if key != "query"},"responseId": data.get("id"),"serverTime": data.get("server_time"),}@@ -499,133 +832,339 @@ def _search_api(return items, artifact-def _sonar_search(+def _agent_failure_artifact(+ query: str,+ deep: bool,+ selection: dict[str, Any],+ *,+ error: str,+ metadata: dict[str, Any] | None = None,+) -> dict[str, Any]:+ return {+ "label": "perplexity",+ "provider": "perplexity",+ "mode": PERPLEXITY_MODE_AGENT,+ "endpoint": "agent-background" if deep else "agent",+ "deep": deep,+ "query": query,+ "error": error,+ "synthesisLength": 0,+ "citationCount": 0,+ **selection,+ **(metadata or {}),+ }+++def _agent_result(query: str,date_range: tuple[str, str],- config: dict,- provider: str,- api_key: str,- url: str,- model: str,deep: bool,-) -> tuple[list[dict], dict]:- from_date, to_date = date_range- timeout = 120 if deep else 30+ data: dict[str, Any],+ selection: dict[str, Any],+ background_metadata: dict[str, Any] | None = None,+) -> tuple[list[dict[str, Any]], dict[str, Any]]:+ _, to_date = date_range+ status = str(data.get("status") or "").lower()+ if status and status != "completed":+ metadata: dict[str, Any] = {+ "responseId": data.get("id"),+ "status": data.get("status"),+ "servedModel": data.get("model"),+ "usage": _usage(data),+ "outputTypes": _output_types(data),+ }+ message = _safe_error_message(data)+ if message:+ metadata["agentErrorMessage"] = message+ incomplete_reason = _safe_incomplete_reason(data)+ if incomplete_reason:+ metadata["incompleteReason"] = incomplete_reason+ if background_metadata:+ metadata.update(background_metadata)+ return [], _agent_failure_artifact(+ query,+ deep,+ selection,+ error=status,+ metadata=metadata,+ )- if deep:- print("[Perplexity] Using Deep Research (~$0.90/query)", file=sys.stderr)+ synthesis = _output_text(data)+ citations = _extract_agent_citations(data)+ if not synthesis:+ _log("Empty Agent API synthesis")+ return [], _agent_failure_artifact(+ query,+ deep,+ selection,+ error="empty_synthesis",+ metadata={+ "responseId": data.get("id"),+ "status": data.get("status"),+ "servedModel": data.get("model"),+ "usage": _usage(data),+ "outputTypes": _output_types(data),+ **(background_metadata or {}),+ },+ )++ _log(f"Got Agent API synthesis ({len(synthesis)} chars) with {len(citations)} citations")+ title_mode = "Deep Research" if deep else "Agent"+ items: list[dict[str, Any]] = [+ {+ "id": "PX1",+ "title": f"Perplexity {title_mode}: {query}",+ "url": "",+ "source_domain": "perplexity.ai",+ "snippet": synthesis[:2000],+ "date": to_date,+ "relevance": 0.9,+ "why_relevant": f"AI synthesis of recent activity for '{query}'",+ "engagement": {"citations": len(citations)},+ "metadata": {+ "citations": citations,+ "usage": _usage(data),+ "perplexity_response_id": data.get("id"),+ },+ }+ ]+ for index, citation in enumerate(citations):+ items.append(+ {+ "id": f"PX{index + 2}",+ "title": citation["title"] or _domain(citation["url"]),+ "url": citation["url"],+ "source_domain": _domain(citation["url"]),+ "snippet": citation.get("snippet") or "",+ "date": citation.get("date"),+ "relevance": 0.7,+ "why_relevant": f"Cited in Perplexity synthesis for '{query}'",+ "engagement": {"citations": 1},+ "metadata": {"citations": [citation]},+ }+ )+ artifact: dict[str, Any] = {+ "label": "perplexity",+ "provider": "perplexity",+ "mode": PERPLEXITY_MODE_AGENT,+ "endpoint": "agent-background" if deep else "agent",+ "deep": deep,+ "query": query,+ "synthesisLength": len(synthesis),+ "citationCount": len(citations),+ "responseId": data.get("id"),+ "status": data.get("status"),+ "servedModel": data.get("model"),+ "usage": _usage(data),+ "outputTypes": _output_types(data),+ **selection,+ }+ if background_metadata:+ artifact.update(background_metadata)+ return items, artifact+++def _agent_search(+ query: str,+ date_range: tuple[str, str],+ config: dict[str, Any],+ api_key: str,+ deep: bool,+) -> tuple[list[dict[str, Any]], dict[str, Any]]:+ from_date, to_date = date_rangeprompt = (f"What has been happening with {query} between {from_date} and {to_date}? ""Include specific dates, names, numbers, and sources.")-+ payload, selection = _build_agent_payload(prompt, date_range, config, deep)headers = {"Authorization": f"Bearer {api_key}","Content-Type": "application/json",}+ _log(f"Querying Perplexity Agent API for '{query}' ({from_date} to {to_date})")- json_data = _build_sonar_payload(prompt, model, date_range, config)- if provider != "perplexity":- json_data.pop("web_search_options", None)- json_data.pop("reasoning_effort", None)+ try:+ if deep:+ data, background_metadata = _poll_agent_background(payload, headers, config)+ else:+ data = http.post(+ PERPLEXITY_AGENT_URL,+ payload,+ headers=headers,+ timeout=_agent_timeout(config),+ retries=1,+ )+ background_metadata = None+ except AgentBackgroundTimeout as exc:+ _log(f"Agent background request timed out: {exc}")+ return [], _agent_failure_artifact(+ query,+ deep,+ selection,+ error="timeout",+ metadata=exc.metadata,+ )+ except AgentBackgroundFailed as exc:+ _log(f"Agent background request failed: {exc}")+ return [], _agent_failure_artifact(+ query,+ deep,+ selection,+ error="failed",+ metadata=exc.metadata,+ )+ except AgentBackgroundPollError as exc:+ _log(f"Agent background poll failed: {exc}")+ return [], _agent_failure_artifact(+ query,+ deep,+ selection,+ error="poll_error",+ metadata=exc.metadata,+ )- _log(f"Querying {provider} {model} for '{query}' ({from_date} to {to_date})")+ return _agent_result(+ query,+ date_range,+ deep,+ data,+ selection,+ background_metadata,+ )- async_artifact = {}- if provider == "perplexity" and deep:- data, async_artifact = _poll_async_sonar(json_data, headers, config)- else:- data = http.post(url, json_data, headers=headers, timeout=timeout)-- # Parse response- choices = data.get("choices", [])- if not choices:- _log("No choices in response")- return [], _empty_async_sonar_artifact(- provider, model, deep, query, data, async_artifact,- "empty_choices",- "Async Deep Research completed without choices",- )++def _openrouter_sonar_search(+ query: str,+ date_range: tuple[str, str],+ api_key: str,+ deep: bool,+) -> tuple[list[dict[str, Any]], dict[str, Any]]:+ """Preserve the pre-Agent OpenRouter Sonar compatibility path."""+ from_date, to_date = date_range+ model = (+ OPENROUTER_MODEL_DEEP_RESEARCH+ if deep+ else OPENROUTER_MODEL_SONAR_PRO+ )+ prompt = (+ f"What has been happening with {query} between {from_date} and {to_date}? "+ "Include specific dates, names, numbers, and sources."+ )+ payload = {+ "model": model,+ "messages": [{"role": "user", "content": prompt}],+ }+ headers = {+ "Authorization": f"Bearer {api_key}",+ "Content-Type": "application/json",+ }+ _log(f"Querying OpenRouter {model} for '{query}' ({from_date} to {to_date})")+ data = http.post(+ OPENROUTER_URL,+ payload,+ headers=headers,+ timeout=120 if deep else 30,+ retries=1,+ )++ choices = data.get("choices")+ if not isinstance(choices, list) or not choices:+ return [], {+ "label": "perplexity",+ "provider": "openrouter",+ "mode": PERPLEXITY_MODE_SONAR,+ "endpoint": "openrouter-chat-completions",+ "model": model,+ "deep": deep,+ "query": query,+ "error": "empty_choices",+ "responseId": data.get("id"),+ "servedModel": data.get("model") or model,+ "usage": _usage(data),+ }choice = choices[0] if isinstance(choices[0], dict) else {}message = choice.get("message")message = message if isinstance(message, dict) else {}- synthesis = message.get("content") or ""- if not isinstance(synthesis, str):- synthesis = ""+ synthesis = message.get("content")+ synthesis = synthesis if isinstance(synthesis, str) else ""if not synthesis:- _log("Empty synthesis content")- return [], _empty_async_sonar_artifact(- provider, model, deep, query, data, async_artifact,- "empty_synthesis",- "Async Deep Research completed with empty synthesis",- )-- citations = _extract_citations(data, choice)-- _log(f"Got synthesis ({len(synthesis)} chars) with {len(citations)} citations")-- # Build items list- items = []-- # Primary item: the synthesis itself- snippet = synthesis[:2000]- items.append({- "id": "PX1",- "title": f"Perplexity {'Deep Research' if deep else 'Sonar'}: {query}",- "url": "",- "source_domain": "perplexity.ai",- "snippet": snippet,- "date": to_date,- "relevance": 0.9,- "why_relevant": f"AI synthesis of recent activity for '{query}'",- "engagement": {"citations": len(citations)},- "metadata": {- "citations": citations,+ return [], {+ "label": "perplexity",+ "provider": "openrouter",+ "mode": PERPLEXITY_MODE_SONAR,+ "endpoint": "openrouter-chat-completions",+ "model": model,+ "deep": deep,+ "query": query,+ "error": "empty_synthesis",+ "responseId": data.get("id"),+ "servedModel": data.get("model") or model,"usage": _usage(data),- **async_artifact,- },- })-- # Individual items for each citation- for i, cit in enumerate(citations):- items.append({- "id": f"PX{i + 2}",- "title": cit["title"] or _domain(cit["url"]),- "url": cit["url"],- "source_domain": _domain(cit["url"]),- "snippet": cit.get("snippet") or "",- "date": cit.get("date"),- "relevance": 0.7,- "why_relevant": f"Cited in Perplexity synthesis for '{query}'",- "engagement": {"citations": 1},- "metadata": {"citations": [cit]},- })+ }- artifact = {+ citations = _extract_openrouter_citations(data, choice)+ title_mode = "Deep Research" if deep else "Sonar"+ items: list[dict[str, Any]] = [+ {+ "id": "PX1",+ "title": f"Perplexity {title_mode}: {query}",+ "url": "",+ "source_domain": "perplexity.ai",+ "snippet": synthesis[:2000],+ "date": to_date,+ "relevance": 0.9,+ "why_relevant": f"AI synthesis of recent activity for '{query}'",+ "engagement": {"citations": len(citations)},+ "metadata": {+ "citations": citations,+ "usage": _usage(data),+ "openrouter_response_id": data.get("id"),+ },+ }+ ]+ for index, citation in enumerate(citations):+ items.append(+ {+ "id": f"PX{index + 2}",+ "title": citation["title"] or _domain(citation["url"]),+ "url": citation["url"],+ "source_domain": _domain(citation["url"]),+ "snippet": citation.get("snippet") or "",+ "date": citation.get("date"),+ "relevance": 0.7,+ "why_relevant": f"Cited in Perplexity synthesis for '{query}'",+ "engagement": {"citations": 1},+ "metadata": {"citations": [citation]},+ }+ )++ return items, {"label": "perplexity",- "provider": provider,+ "provider": "openrouter","mode": PERPLEXITY_MODE_SONAR,- "endpoint": "async-sonar" if async_artifact else "sonar",+ "endpoint": "openrouter-chat-completions","model": model,"deep": deep,"query": query,"synthesisLength": len(synthesis),"citationCount": len(citations),+ "responseId": data.get("id"),+ "servedModel": data.get("model") or model,"usage": _usage(data),- **async_artifact,}- return items, artifact--def _merge_sonar_and_search(sonar_items: list[dict], search_items: list[dict]) -> list[dict]:- if not sonar_items:+def _merge_agent_and_search(+ agent_items: list[dict[str, Any]],+ search_items: list[dict[str, Any]],+) -> list[dict[str, Any]]:+ if not agent_items:return search_items- merged = sonar_items[:1]+ merged = agent_items[:1]seen_urls = {item.get("url") for item in merged if item.get("url")}- for item in [*search_items, *sonar_items[1:]]:+ for item in [*search_items, *agent_items[1:]]:url = item.get("url")if url and url in seen_urls:continue@@ -635,111 +1174,147 @@ def _merge_sonar_and_search(sonar_items: list[dict], search_items: list[dict]) -return merged+def _top_level_failure(+ query: str,+ mode: str,+ deep: bool,+ exc: Exception,+ provider: str = "perplexity",+) -> dict[str, Any]:+ artifact = _error_artifact(exc)+ if provider == "openrouter":+ endpoint = "openrouter-chat-completions"+ elif deep:+ endpoint = "agent-background"+ elif mode == PERPLEXITY_MODE_SEARCH:+ endpoint = "search"+ else:+ endpoint = "agent"+ artifact.update(+ {+ "label": "perplexity",+ "provider": provider,+ "mode": mode,+ "endpoint": endpoint,+ "deep": deep,+ "query": query,+ }+ )+ return artifact++def search(query: str,date_range: tuple[str, str],- config: dict,+ config: dict[str, Any],deep: bool = False,-) -> tuple[list[dict], dict]:- """Search via Perplexity Sonar Pro or Deep Research.-- Args:- query: Search topic- date_range: (from_date, to_date) as YYYY-MM-DD strings- config: Must contain PERPLEXITY_API_KEY or OPENROUTER_API_KEY- deep: Use Deep Research model (~$0.90/query) instead of Sonar Pro+) -> tuple[list[dict[str, Any]], dict[str, Any]]:+ """Search through Perplexity's Agent API or raw Search API.- Returns:- Tuple of (items list, artifact dict).+ Normal synthesis uses the controlled Agent profile. Search API mode remains+ available for raw ranked rows. Deep Research is a dynamic high-preset+ background run and requires an explicit --deep-research invocation."""- resolved = _provider(config, deep)+ resolved = _provider(config)if not resolved:- _log("No PERPLEXITY_API_KEY or OPENROUTER_API_KEY configured, skipping")+ _log(+ "No PERPLEXITY_API_KEY or OPENROUTER_API_KEY configured, skipping"+ )return [], {}- provider, api_key, url, model = resolved- mode = _mode(config, provider, deep)+ provider, api_key = resolved+ mode = _mode(config, deep, provider)try:+ if provider == "openrouter":+ result = _openrouter_sonar_search(+ query,+ date_range,+ api_key,+ deep,+ )+ if deep:+ _log_deep_receipt(result[1])+ return resultif mode == PERPLEXITY_MODE_SEARCH:return _search_api(query, date_range, config, api_key)if mode == PERPLEXITY_MODE_BOTH:- search_items: list[dict] = []- sonar_items: list[dict] = []- search_artifact: dict = {}- sonar_artifact: dict = {}+ search_items: list[dict[str, Any]] = []+ agent_items: list[dict[str, Any]] = []+ search_artifact: dict[str, Any] = {}+ agent_artifact: dict[str, Any] = {}try:- search_items, search_artifact = _search_api(query, date_range, config, api_key)- except Exception as e:- _log(f"Search API leg failed in both mode: {e}")- search_artifact = _error_artifact(e)+ search_items, search_artifact = _search_api(+ query,+ date_range,+ config,+ api_key,+ )+ except Exception as exc:+ _log(f"Search API leg failed in both mode: {exc}")+ search_artifact = _error_artifact(exc)try:- sonar_items, sonar_artifact = _sonar_search(- query, date_range, config, provider, api_key, url, model, deep+ agent_items, agent_artifact = _agent_search(+ query,+ date_range,+ config,+ api_key,+ deep=False,)- except Exception as e:- _log(f"Sonar leg failed in both mode: {e}")- sonar_artifact = _error_artifact(e)- items = _merge_sonar_and_search(sonar_items, search_items)+ except Exception as exc:+ _log(f"Agent API leg failed in both mode: {exc}")+ agent_artifact = _error_artifact(exc)+ items = _merge_agent_and_search(agent_items, search_items)return items, {"label": "perplexity","provider": "perplexity","mode": PERPLEXITY_MODE_BOTH,"query": query,"search": search_artifact,- "sonar": sonar_artifact,+ "agent": agent_artifact,"itemCount": len(items),}- return _sonar_search(query, date_range, config, provider, api_key, url, model, deep)- except http.HTTPError as e:- if e.status_code == 401:+ result = _agent_search(query, date_range, config, api_key, deep)+ if deep:+ _log_deep_receipt(result[1])+ return result+ except http.HTTPError as exc:+ if exc.status_code == 401:_log(f"Invalid {provider} API key (401)")- elif e.status_code == 429:+ elif exc.status_code == 429:_log(f"Rate limited by {provider} (429)")else:- _log(f"HTTP error: {e}")- return [], {}- except AsyncDeepResearchTimeout as e:- _log(f"Request timed out: {e}")- return [], {- "label": "perplexity",- "provider": provider,- "mode": PERPLEXITY_MODE_SONAR,- "endpoint": "async-sonar",- "model": model,- "deep": deep,- "query": query,- "error": "timeout",- **e.metadata,- }- except AsyncDeepResearchFailed as e:- _log(f"Deep Research failed: {e}")- return [], {- "label": "perplexity",- "provider": provider,- "mode": PERPLEXITY_MODE_SONAR,- "endpoint": "async-sonar",- "model": model,- "deep": deep,- "query": query,- "error": "failed",- **e.metadata,- }- except AsyncDeepResearchPollError as e:- _log(f"Deep Research poll failed: {e}")- return [], {- "label": "perplexity",- "provider": provider,- "mode": PERPLEXITY_MODE_SONAR,- "endpoint": "async-sonar",- "model": model,- "deep": deep,- "query": query,- "error": "poll_error",- **e.metadata,- }- except TimeoutError as e:- _log(f"Request timed out: {e}")- return [], {"label": "perplexity", "provider": provider, "error": "timeout"}- except Exception as e:- _log(f"Request failed: {e}")- return [], {}+ _log(f"HTTP error: {exc}")+ artifact = _top_level_failure(+ query,+ mode,+ deep,+ exc,+ provider=provider,+ )+ if deep:+ _log_deep_receipt(artifact)+ return [], artifact+ except TimeoutError as exc:+ _log(f"Request timed out: {exc}")+ artifact = _top_level_failure(+ query,+ mode,+ deep,+ exc,+ provider=provider,+ )+ if deep:+ _log_deep_receipt(artifact)+ return [], artifact+ except Exception as exc:+ _log(f"Request failed: {exc}")+ artifact = _top_level_failure(+ query,+ mode,+ deep,+ exc,+ provider=provider,+ )+ if deep:+ _log_deep_receipt(artifact)+ return [], artifactdiff --git a/skills/last30days/scripts/lib/pipeline.py b/skills/last30days/scripts/lib/pipeline.pyindex 5c40da43..7dba5e9e 100644--- a/skills/last30days/scripts/lib/pipeline.py+++ b/skills/last30days/scripts/lib/pipeline.py@@ -108,6 +108,49 @@ MAX_SOURCE_FETCHES: dict[str, int] = {"x": 2, "jobs": 1, "linkedin": 1, "stocktwits": 1, "trustpilot": 1, "amazon": 1,}+_FAILURE_SPECIFICITY = {+ health.AUTH_FAILED: 0,+ health.RATE_LIMITED: 1,+ health.SCHEMA_DRIFT: 2,+ health.TIMEOUT: 3,+ health.UNREACHABLE: 4,+ health.ERROR: 5,+}+++@dataclass+class PaidSourceBudget:+ """Command-wide, thread-safe budget for paid source adapter calls."""++ used: int = 0+ owner: str | None = None+ _lock: Any = field(default_factory=threading.Lock, repr=False)++ def try_consume(self, limit: int, *, claimant: str | None = None) -> bool:+ with self._lock:+ if self.owner is not None and claimant != self.owner:+ return False+ if self.used >= limit:+ return False+ self.used += 1+ return True+++def _source_fetch_cap(source: str, config: dict[str, Any]) -> int | None:+ """Return the effective per-run cap for one source.++ Every Perplexity adapter call is paid, and ``both`` performs two paid POSTs.+ A generic fetch-cap override must not multiply either normal or Deep+ Research mode across planner subqueries.+ """+ override = config.get("_max_source_fetches")+ if source == "perplexity":+ return 1 if override is None else min(1, int(override))+ cap = MAX_SOURCE_FETCHES.get(source)+ if cap is not None and override is not None:+ return int(override)+ return cap+def _resolve_depth_settings(depth: str, config: dict[str, Any]) -> dict[str, int]:"""Depth profile with optional CLI cap overrides applied (issue #716).@@ -140,7 +183,11 @@ RELATED_HANDLE_COUNT_PER = 3def _has_perplexity_provider(config: dict[str, Any]) -> bool:- return bool(config.get("PERPLEXITY_API_KEY") or config.get("OPENROUTER_API_KEY"))+ # Prefer direct Agent/Search APIs, but preserve the synchronous OpenRouter+ # Sonar fallback for existing installs.+ return bool(+ config.get("PERPLEXITY_API_KEY") or config.get("OPENROUTER_API_KEY")+ )MOCK_AVAILABLE_SOURCES = ["reddit",@@ -264,7 +311,7 @@ def available_sources(available.append("grounding")if requested_sources and "jobs" in requested_sources:available.append("jobs")- # Perplexity Sonar: opt-in additive source via INCLUDE_SOURCES=perplexity+ # Perplexity Agent API: opt-in additive source via INCLUDE_SOURCES=perplexityif _has_perplexity_provider(config) and ("perplexity" in include_sources or (requested_sources and "perplexity" in requested_sources)):@@ -2070,6 +2117,17 @@ def run(plan.source_weights["corpus"] = 1.0plan.source_weights = planner._normalize_weights(plan.source_weights)+ # Add the paid-only Perplexity lane after all normal-source safety nets.+ # This preserves the planner's primary subquery, gives the bounded paid+ # call the whole user topic, and prevents grounding, jobs, or corpus from+ # being attached to the dedicated lane.+ _ensure_perplexity_in_plan(+ plan,+ topic,+ available,+ force=bool(config.get("_deep_research")),+ )+# Always-on planner trace. Emits one summary line plus one per subquery# so retrieval-breadth failures like the 2026-04-19 Hermes Agent Use Cases# disaster are visible without --debug. Stderr only; does not leak into@@ -2290,16 +2348,31 @@ def run(# Enforce per-source fetch cap. A CLI override (issue #716) raises# the cap for capped sources so every X subquery in a multi-angle# --plan fetches, instead of only the first two.- cap = MAX_SOURCE_FETCHES.get(source)- _cap_override = config.get("_max_source_fetches")- if cap is not None and _cap_override is not None:- # `is not None` so --max-source-fetches 0 (disable fetching a- # capped source) is honored instead of falling back to default.- cap = int(_cap_override)+ cap = _source_fetch_cap(source, config)if cap is not None:+ if cap <= 0:+ continuecurrent = source_fetch_count.get(source, 0)if current >= cap:continue+ shared_paid_budget = config.get("_perplexity_paid_budget")+ if (+ source == "perplexity"+ and isinstance(shared_paid_budget, PaidSourceBudget)+ and not shared_paid_budget.try_consume(+ cap,+ claimant=topic,+ )+ ):+ bundle.artifacts.setdefault("paid_source_budget", {})[+ "perplexity"+ ] = {+ "state": "skipped-budget",+ "attempted": False,+ "owner": shared_paid_budget.owner,+ "claimant": topic,+ }+ continuesource_fetch_count[source] = current + 1bundle.mark_attempted(source)futures[@@ -3034,6 +3107,46 @@ def _ensure_jobs_in_plan(subquery.sources.append("jobs")+def _ensure_perplexity_in_plan(+ plan: schema.QueryPlan,+ topic: str,+ available: list[str],+ *,+ force: bool,+) -> None:+ """Route a bounded paid Perplexity action through the whole topic.++ Deep Research forces its explicit lane. Normal modes are rerouted only when+ the sanitized plan already selected Perplexity.+ """+ if "perplexity" not in available:+ return+ planned = any(+ "perplexity" in subquery.sources for subquery in plan.subqueries+ )+ if not force and not planned:+ return+ retained: list[schema.SubQuery] = []+ for subquery in plan.subqueries:+ sources = [+ source for source in subquery.sources if source != "perplexity"+ ]+ if sources:+ retained.append(replace(subquery, sources=sources))+ retained.append(+ schema.SubQuery(+ label="deep-research" if force else "perplexity-whole-topic",+ search_query=topic,+ ranking_query=f"What current source-grounded evidence matters for {topic}?",+ sources=["perplexity"],+ weight=1.0,+ ),+ )+ plan.subqueries = planner._normalize_subquery_weights(retained)+ plan.source_weights.setdefault("perplexity", 1.0)+ plan.source_weights = planner._normalize_weights(plan.source_weights)++def _company_topic_likely(topic: str) -> bool:text = topic.strip()if not text:@@ -3201,22 +3314,45 @@ def _legacy_artifact_outcome(explicit = artifact.get("_source_outcome")if isinstance(explicit, dict):return explicit- if source == "perplexity" and artifact.get("error"):- error = str(artifact["error"])- detail = str(- artifact.get("asyncErrorMessage")- or artifact.get("message")- or error- )- state = (- health.TIMEOUT- if error.lower() == "timeout"- else http.classify_failure(- status_code=artifact.get("statusCode"),- message=f"{error}: {detail}",+ if source == "perplexity":+ candidates: list[tuple[str | None, dict[str, Any]]] = [(None, artifact)]+ if artifact.get("mode") == "both":+ for leg in ("search", "agent"):+ value = artifact.get(leg)+ if isinstance(value, dict):+ candidates.append((leg, value))+ outcomes: list[dict[str, Any]] = []+ for leg, candidate in candidates:+ if not candidate.get("error"):+ continue+ error = str(candidate["error"])+ detail = str(+ candidate.get("backgroundErrorMessage")+ or candidate.get("backgroundPollError")+ or candidate.get("agentErrorMessage")+ or candidate.get("asyncErrorMessage")+ or candidate.get("message")+ or error+ )+ if leg:+ detail = f"{leg} leg: {detail}"+ status_code = candidate.get("statusCode")+ if status_code is None:+ status_code = candidate.get("backgroundPollStatusCode")+ state = (+ health.TIMEOUT+ if error.lower() == "timeout"+ else http.classify_failure(+ status_code=status_code,+ message=f"{error}: {detail}",+ )+ )+ outcomes.append(_outcome_artifact(state, detail)["_source_outcome"])+ if outcomes:+ return min(+ outcomes,+ key=lambda outcome: _FAILURE_SPECIFICITY.get(outcome["state"], 9),)- )- return _outcome_artifact(state, detail)["_source_outcome"]if (source == "grounding"and artifact.get("reason") == "keyless-search-unavailable"@@ -3240,14 +3376,6 @@ def _resolve_stream_outcome(# Pick the most specific failure rather than the last-appended one:# parallel workers append in nondeterministic order, and an auth failure# must not be masked by a later 429 (wrong doctor prescription).- _FAILURE_SPECIFICITY = {- health.AUTH_FAILED: 0,- health.RATE_LIMITED: 1,- health.SCHEMA_DRIFT: 2,- health.TIMEOUT: 3,- health.UNREACHABLE: 4,- health.ERROR: 5,- }failure = min(failures,key=lambda f: _FAILURE_SPECIFICITY.get(f.outcome_state, 9),@@ -3795,7 +3923,7 @@ def _retry_thin_sources(# MAX_SOURCE_FETCHES and re-resolving WITHOUT the caller's# --trustpilot-domain (a lookalike-misattribution path). Its thin result# is its normal success state; never retry it here.- _skip = (skip_sources or set()) | {"trustpilot"}+ _skip = (skip_sources or set()) | {"trustpilot", "perplexity"}thin_sources = [sourcefor source in planned_sources@@ -4905,4 +5033,3 @@ def _mock_stream_results(source: str, subquery: schema.SubQuery) -> tuple[list[d"resultCount": 1,}return payloads.get(source, []), {}-diff --git a/tests/test_cli_v3.py b/tests/test_cli_v3.pyindex 2ec657dd..4714fa65 100644--- a/tests/test_cli_v3.py+++ b/tests/test_cli_v3.py@@ -2,6 +2,7 @@import contextlibimport jsonimport io+import osimport shutilimport tempfileimport subprocess@@ -131,7 +132,7 @@ class CliV3Tests(unittest.TestCase):)self.assertIn("threads", available)- def test_explicit_perplexity_search_uses_openrouter_key_without_include_sources(self):+ def test_explicit_perplexity_search_uses_openrouter_fallback(self):available = cli.pipeline.available_sources({"OPENROUTER_API_KEY": "test-key", "INCLUDE_SOURCES": ""},requested_sources=["perplexity"],@@ -179,6 +180,38 @@ class CliV3Tests(unittest.TestCase):)self.assertIn("LAST30DAYS_DEFAULT_SEARCH", str(exc.exception))+ def test_deep_research_preserves_default_source_selection(self):+ self.assertIsNone(cli.add_deep_research_source(None))++ def test_deep_research_extends_an_explicit_source_selection(self):+ self.assertEqual(+ ["reddit", "perplexity"],+ cli.add_deep_research_source(["reddit"]),+ )+ self.assertEqual(+ ["reddit", "perplexity"],+ cli.add_deep_research_source(["reddit", "perplexity"]),+ )++ def test_deep_research_enables_exact_include_token(self):+ config = {"INCLUDE_SOURCES": "notperplexity,reddit"}++ cli.enable_deep_research_source(config)++ self.assertEqual(+ ["notperplexity", "reddit", "perplexity"],+ config["INCLUDE_SOURCES"].split(","),+ )++ def test_deep_research_rejects_exact_exclusion(self):+ config = {"EXCLUDE_SOURCES": "reddit,Perplexity"}++ with self.assertRaisesRegex(+ ValueError,+ "conflicts with EXCLUDE_SOURCES=perplexity",+ ):+ cli.enable_deep_research_source(config)+def test_build_parser_accepts_days_alias_and_preserves_topic_tokens(self):parser = cli.build_parser()args, extra = parser.parse_known_args(["--days", "7", "biosecurity", "ai", "agents"])@@ -194,6 +227,162 @@ class CliV3Tests(unittest.TestCase):self.assertEqual("keyless", args.web_backend)self.assertEqual([], extra)+ def test_deep_research_help_keeps_openrouter_fallback(self):+ parser = cli.build_parser()+ action = next(+ candidate+ for candidate in parser._actions+ if "--deep-research" in candidate.option_strings+ )+ self.assertIn("PERPLEXITY_API_KEY", action.help)+ self.assertIn("OPENROUTER_API_KEY", action.help)+ self.assertIn("cannot be combined with competitor or vs-mode", action.help)++ def test_deep_research_rejects_modes_without_a_positional_topic(self):+ for argv in (+ ["last30days.py", "--discover", "agents", "--deep-research"],+ ["last30days.py", "--drill", "cluster-1", "--deep-research"],+ ):+ with self.subTest(argv=argv), mock.patch.object(+ cli.env,+ "get_config",+ return_value={},+ ), mock.patch.object(+ cli,+ "_run_discover",+ ) as discover_mock, mock.patch.object(+ cli,+ "_run_drill",+ ) as drill_mock, mock.patch.dict(+ os.environ,+ {"LAST30DAYS_SKIP_PREFLIGHT": "1"},+ clear=False,+ ), mock.patch.object(sys, "argv", argv):+ stderr = io.StringIO()+ with redirect_stderr(stderr):+ rc = cli.main()++ self.assertEqual(2, rc)+ discover_mock.assert_not_called()+ drill_mock.assert_not_called()+ self.assertIn("requires a normal positional topic", stderr.getvalue())++ def test_deep_research_rejects_competitor_fanout_before_pipeline_run(self):+ diag = {+ "available_sources": ["perplexity"],+ "providers": {"google": False, "openai": False, "xai": False},+ "x_backend": None,+ "bird_installed": True,+ "bird_authenticated": False,+ "bird_username": None,+ "native_web_backend": None,+ }+ with mock.patch.object(+ cli.env,+ "get_config",+ return_value={"PERPLEXITY_API_KEY": "pplx-test"},+ ), mock.patch.object(+ cli.pipeline,+ "diagnose",+ return_value=diag,+ ) as diagnose_mock, mock.patch.object(+ cli.pipeline,+ "run",+ ) as run_mock, mock.patch.object(+ cli.ui,+ "ProgressDisplay",+ return_value=mock.Mock(),+ ), mock.patch.object(+ sys,+ "argv",+ [+ "last30days.py",+ "Alpha",+ "vs",+ "Beta",+ "--mock",+ "--deep-research",+ ],+ ):+ stderr = io.StringIO()+ with redirect_stderr(stderr):+ rc = cli.main()++ self.assertEqual(2, rc)+ diagnose_mock.assert_not_called()+ run_mock.assert_not_called()+ self.assertIn(+ "one paid Deep Research run per user action",+ stderr.getvalue(),+ )++ def test_openrouter_deep_research_bypasses_hosted_and_adds_source(self):+ report = self.make_report(topic="why AI safety matters")+ diag = {+ "available_sources": ["reddit", "perplexity"],+ "providers": {"google": False, "openai": False, "xai": False},+ "x_backend": None,+ "bird_installed": True,+ "bird_authenticated": False,+ "bird_username": None,+ "native_web_backend": None,+ }+ with mock.patch.object(+ cli.env,+ "get_config",+ return_value={"OPENROUTER_API_KEY": "openrouter-test"},+ ), mock.patch.object(+ cli.env,+ "read_secret_env",+ return_value="hosted-test-key",+ ), mock.patch.object(+ cli.pipeline,+ "diagnose",+ return_value=diag,+ ), mock.patch.object(+ cli.pipeline,+ "run",+ return_value=report,+ ) as run_mock, mock.patch(+ "lib.hosted.run_hosted",+ ) as hosted_mock, mock.patch.object(+ cli.ui,+ "ProgressDisplay",+ return_value=mock.Mock(),+ ), mock.patch.object(+ cli,+ "emit_output",+ return_value="# rendered",+ ), mock.patch.dict(+ os.environ,+ {+ "LAST30DAYS_API_BASE": "https://hosted.example.test",+ "LAST30DAYS_SKIP_PREFLIGHT": "1",+ },+ clear=False,+ ), mock.patch.object(+ sys,+ "argv",+ [+ "last30days.py",+ "why",+ "AI",+ "safety",+ "matters",+ "--deep-research",+ "--search",+ "reddit",+ ],+ ):+ with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):+ rc = cli.main()++ self.assertEqual(0, rc)+ hosted_mock.assert_not_called()+ requested_sources = run_mock.call_args.kwargs["requested_sources"]+ self.assertEqual(["reddit", "perplexity"], requested_sources)+ self.assertTrue(run_mock.call_args.kwargs["config"]["_deep_research"])+def test_build_parser_still_accepts_other_web_backend_values(self):parser = cli.build_parser()for value in ("auto", "brave", "exa", "serper", "parallel", "none"):diff --git a/tests/test_doctor.py b/tests/test_doctor.pyindex b523194f..5aa8b0a0 100644--- a/tests/test_doctor.py+++ b/tests/test_doctor.py@@ -202,6 +202,30 @@ class KeylessEnvironment(unittest.TestCase):self.assertIn("last30days doctor", out)+class PerplexityKeyBoundary(unittest.TestCase):+ def test_openrouter_only_enables_sonar_fallback(self):+ record = _build(+ {+ "OPENROUTER_API_KEY": "dummy-openrouter-secret-000",+ "INCLUDE_SOURCES": "perplexity",+ }+ )["sources"]["perplexity"]++ self.assertEqual("ok", record["status"])+ self.assertIn("PERPLEXITY_API_KEY", record["requires"])+ self.assertIn("OPENROUTER_API_KEY", record["requires"])++ def test_direct_perplexity_key_with_opt_in_is_ready(self):+ record = _build(+ {+ "PERPLEXITY_API_KEY": "dummy-perplexity-secret-000",+ "INCLUDE_SOURCES": "perplexity",+ }+ )["sources"]["perplexity"]++ self.assertEqual("ok", record["status"])++class GitHubAuthDetection(unittest.TestCase):"""GitHub doctor auth must mirror the real fetcher token source."""diff --git a/tests/test_env_v3.py b/tests/test_env_v3.pyindex 1544c5bc..7d4d1882 100644--- a/tests/test_env_v3.py+++ b/tests/test_env_v3.py@@ -50,6 +50,11 @@ class EnvV3Tests(unittest.TestCase):overrides = {"LAST30DAYS_PERPLEXITY_MODE": "search","LAST30DAYS_PERPLEXITY_MODEL": "sonar-reasoning-pro",+ "LAST30DAYS_PERPLEXITY_AGENT_MODEL": "perplexity/sonar",+ "LAST30DAYS_PERPLEXITY_AGENT_PRESET": "low",+ "LAST30DAYS_PERPLEXITY_AGENT_MAX_STEPS": "4",+ "LAST30DAYS_PERPLEXITY_AGENT_MAX_OUTPUT_TOKENS": "8192",+ "LAST30DAYS_PERPLEXITY_AGENT_TIMEOUT_SECONDS": "120","LAST30DAYS_PERPLEXITY_MAX_RESULTS": "3","LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE": "low","LAST30DAYS_PERPLEXITY_SEARCH_MODE": "academic",diff --git a/tests/test_http_v3.py b/tests/test_http_v3.pyindex 3702df01..29af27e0 100644--- a/tests/test_http_v3.py+++ b/tests/test_http_v3.py@@ -1,5 +1,6 @@import urllib.errorimport unittest+import timefrom unittest.mock import patch, MagicMockfrom lib import http@@ -38,6 +39,91 @@ class Test429RetryLimit(unittest.TestCase):self.assertEqual(mock_urlopen.call_count, 3)+ @patch("lib.http.urllib.request.urlopen")+ @patch("lib.http.time.sleep")+ @patch("lib.http.time.monotonic", side_effect=[0.0, 0.5, 0.5])+ def test_shared_deadline_stops_retry_before_backoff_crosses_it(+ self,+ _mock_monotonic,+ mock_sleep,+ mock_urlopen,+ ):+ mock_urlopen.side_effect = urllib.error.HTTPError(+ "http://example.com", 500, "Internal Server Error", {}, None+ )++ with self.assertRaises(http.HTTPError) as caught:+ http.request(+ "GET",+ "http://example.com",+ retries=3,+ deadline_monotonic=1.0,+ )++ self.assertEqual(http.health.TIMEOUT, caught.exception.outcome_state)+ self.assertEqual(1, mock_urlopen.call_count)+ mock_sleep.assert_not_called()++ @patch("lib.http.urllib.request.urlopen")+ @patch("lib.http.time.monotonic", side_effect=[0.0, 0.5, 1.5])+ def test_shared_deadline_rejects_response_that_finishes_late(+ self,+ _mock_monotonic,+ mock_urlopen,+ ):+ mock_urlopen.return_value = _mock_response()++ with self.assertRaises(http.DeadlineExceeded):+ http.request(+ "GET",+ "http://example.com",+ retries=1,+ deadline_monotonic=1.0,+ )++ @patch("lib.http.urllib.request.urlopen")+ def test_shared_deadline_stops_waiting_during_slow_body_read(+ self,+ mock_urlopen,+ ):+ response = _mock_response()++ def slow_read():+ time.sleep(0.2)+ return b'{"ok": true}'++ response.read.side_effect = slow_read+ mock_urlopen.return_value = response+ started = time.monotonic()++ with self.assertRaises(http.DeadlineExceeded):+ http.request(+ "GET",+ "http://example.com",+ retries=1,+ deadline_monotonic=started + 0.02,+ )++ self.assertLess(time.monotonic() - started, 0.12)++ @patch("lib.http.urllib.request.urlopen")+ def test_worker_socket_timeout_is_not_wall_deadline_expiration(+ self,+ mock_urlopen,+ ):+ mock_urlopen.side_effect = TimeoutError("early socket timeout")++ with self.assertRaises(http.HTTPError) as caught:+ http.request(+ "GET",+ "http://example.com",+ retries=1,+ deadline_monotonic=time.monotonic() + 600,+ )++ self.assertNotIsInstance(caught.exception, http.DeadlineExceeded)+ self.assertEqual(http.health.TIMEOUT, caught.exception.outcome_state)+def _mock_response(body: str = '{"ok": true}', status: int = 200):resp = MagicMock()diff --git a/tests/test_last_run_state.py b/tests/test_last_run_state.pyindex 3efb47be..2491539f 100644--- a/tests/test_last_run_state.py+++ b/tests/test_last_run_state.py@@ -185,6 +185,43 @@ class LastRunStateTests(unittest.TestCase):self.assertIn("Cached synthesis body.", stdout.getvalue())self.assertIn("Reusing cached report data", stderr.getvalue())+ def test_deep_research_bypasses_html_synthesis_cache(self):+ with tempfile.TemporaryDirectory() as tmp:+ config_dir = Path(tmp) / "config"+ synthesis_path = Path(tmp) / "synthesis.md"+ synthesis_path.write_text("# Cached synthesis", encoding="utf-8")+ with mock.patch.object(cli.env, "CONFIG_DIR", config_dir):+ cli._write_last_run("OpenClaw", _report("OpenClaw"))++ fresh_report = _report("OpenClaw")+ config = {"OPENROUTER_API_KEY": "or-test"}+ with mock.patch.object(cli.env, "CONFIG_DIR", config_dir), \+ mock.patch.object(cli.env, "get_config", return_value=config), \+ mock.patch.object(cli.pipeline, "diagnose", return_value=_diag()), \+ mock.patch.object(cli.pipeline, "run", return_value=fresh_report) as run_mock, \+ mock.patch.object(cli.ui, "ProgressDisplay"), \+ mock.patch.object(cli, "_load_last_report_cache") as cache_mock, \+ mock.patch.object(sys, "argv", [+ "last30days.py",+ "OpenClaw",+ "--deep-research",+ "--emit=html",+ "--synthesis-file",+ str(synthesis_path),+ ]), \+ mock.patch.dict(+ os.environ,+ {"LAST30DAYS_SKIP_PREFLIGHT": "1"},+ clear=False,+ ):+ with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):+ rc = cli.main()++ self.assertEqual(0, rc)+ cache_mock.assert_not_called()+ run_mock.assert_called_once()+ self.assertTrue(run_mock.call_args.kwargs["config"]["_deep_research"])+def test_html_synthesis_reuses_cached_comparison_reports(self):with tempfile.TemporaryDirectory() as tmp:config_dir = Path(tmp) / "config"diff --git a/tests/test_perplexity.py b/tests/test_perplexity.pyindex bba4cbc5..7e983a21 100644--- a/tests/test_perplexity.py+++ b/tests/test_perplexity.py@@ -4,106 +4,387 @@ from unittest.mock import patchfrom lib import perplexity-class PerplexityProviderTests(unittest.TestCase):- def test_direct_perplexity_key_wins_and_parses_search_results(self):- response = {- "choices": [{"message": {"content": "Direct synthesis"}}],- "citations": ["https://example.com/a"],- "search_results": [+def _agent_response(+ text: str = "Agent synthesis",+ *,+ response_id: str = "agent-1",+ status: str = "completed",+ model: str = "perplexity/sonar",+ citations: list[dict] | None = None,+ include_output_text: bool = True,+) -> dict:+ citation_parts = [+ {+ "type": "output_text",+ "text": text,+ "annotations": [{- "title": "Example A",- "url": "https://example.com/a",- "date": "2026-06-01",- "snippet": "Direct source snippet",- "source": "web",+ "url_citation": {+ "url": citation["url"],+ "title": citation.get("title", ""),+ }}+ for citation in citations or []],}+ ]+ response = {+ "id": response_id,+ "status": status,+ "model": model,+ "output": [+ {"type": "message", "content": citation_parts},+ {"type": "search_results", "results": citations or []},+ ],+ "usage": {"total_tokens": 123},+ }+ if include_output_text:+ response["output_text"] = text+ return response+++class PerplexityAgentTests(unittest.TestCase):+ def test_controlled_agent_uses_direct_key_and_explicit_web_search(self):+ citations = [+ {+ "title": "Example A",+ "url": "https://example.com/a",+ "date": "2026-06-01",+ "snippet": "Direct source snippet",+ }+ ]+ response = _agent_response("Direct synthesis", citations=citations)+ config = {+ "PERPLEXITY_API_KEY": "pplx-test",+ "OPENROUTER_API_KEY": "or-test",+ "LAST30DAYS_PERPLEXITY_MAX_RESULTS": "3",+ "LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE": "low",+ "LAST30DAYS_PERPLEXITY_COUNTRY": "us",+ "LAST30DAYS_PERPLEXITY_DOMAIN_FILTER": "example.com,example.org",+ "LAST30DAYS_PERPLEXITY_RECENCY_FILTER": "year",+ "LAST30DAYS_PERPLEXITY_REASONING_EFFORT": "high",+ "LAST30DAYS_PERPLEXITY_AGENT_MAX_STEPS": "4",+ }with patch("lib.perplexity.http.post", return_value=response) as post:items, artifact = perplexity.search("test topic",("2026-05-01", "2026-06-01"),- {- "PERPLEXITY_API_KEY": "pplx-test",- "OPENROUTER_API_KEY": "or-test",- },+ config,)url, payload = post.call_args.args[:2]headers = post.call_args.kwargs["headers"]- self.assertEqual(perplexity.PERPLEXITY_URL, url)+ tool = payload["tools"][0]+ self.assertEqual(perplexity.PERPLEXITY_AGENT_URL, url)self.assertEqual("Bearer pplx-test", headers["Authorization"])- self.assertEqual("sonar-pro", payload["model"])+ self.assertEqual(1, post.call_args.kwargs["retries"])+ self.assertEqual("perplexity/sonar", payload["model"])+ self.assertIn("input", payload)+ self.assertIn("instructions", payload)+ self.assertEqual(4, payload["max_steps"])+ self.assertEqual({"effort": "high"}, payload["reasoning"])+ self.assertEqual({"type": "web_search"}, payload["tool_choice"])+ self.assertEqual("web_search", tool["type"])+ self.assertEqual(3, tool["max_results"])+ self.assertEqual("low", tool["search_context_size"])+ self.assertEqual({"country": "US"}, tool["user_location"])self.assertEqual(- "05/01/2026",- payload["web_search_options"]["search_after_date_filter"],+ ["example.com", "example.org"],+ tool["filters"]["search_domain_filter"],)+ self.assertEqual("05/01/2026", tool["filters"]["search_after_date_filter"])+ self.assertEqual("06/01/2026", tool["filters"]["search_before_date_filter"])+ self.assertNotIn("search_recency_filter", tool["filters"])+ self.assertNotIn("preset", payload)++ self.assertEqual("perplexity", artifact["provider"])+ self.assertEqual("agent", artifact["mode"])+ self.assertEqual("agent", artifact["endpoint"])+ self.assertEqual("perplexity/sonar", artifact["model"])+ self.assertEqual(perplexity.PERPLEXITY_CONTROLLED_PROFILE, artifact["profile"])+ self.assertFalse(artifact["dynamicPreset"])+ self.assertEqual("agent-1", artifact["responseId"])+ self.assertEqual("perplexity/sonar", artifact["servedModel"])+ self.assertEqual(["message", "search_results"], artifact["outputTypes"])+ self.assertNotIn("input", artifact["request"])+ self.assertNotIn("instructions", artifact["request"])+ self.assertEqual({"effort": "high"}, artifact["request"]["reasoning"])self.assertEqual(- "06/01/2026",- payload["web_search_options"]["search_before_date_filter"],+ {"type": "web_search"},+ artifact["request"]["tool_choice"],)- self.assertEqual("perplexity", artifact["provider"])- self.assertEqual("sonar-pro", artifact["model"])self.assertEqual("Example A", items[1]["title"])self.assertEqual("Direct source snippet", items[1]["snippet"])- def test_direct_model_config_selects_supported_sonar_model(self):- response = {- "choices": [{"message": {"content": "Reasoned synthesis"}}],- "citations": [],- "search_results": [],- }+ def test_legacy_sonar_mode_is_an_agent_alias(self):+ response = _agent_response()with patch("lib.perplexity.http.post", return_value=response) as post:_, artifact = perplexity.search("test topic",("2026-05-01", "2026-06-01"),{"PERPLEXITY_API_KEY": "pplx-test",- "LAST30DAYS_PERPLEXITY_MODEL": "sonar-reasoning-pro",- "LAST30DAYS_PERPLEXITY_REASONING_EFFORT": "high",+ "LAST30DAYS_PERPLEXITY_MODE": "sonar",+ "LAST30DAYS_PERPLEXITY_MODEL": "sonar-pro",+ },+ )++ self.assertEqual(perplexity.PERPLEXITY_AGENT_URL, post.call_args.args[0])+ self.assertEqual(1, post.call_args.kwargs["retries"])+ self.assertEqual("perplexity/sonar", post.call_args.args[1]["model"])+ self.assertEqual("agent", artifact["mode"])++ def test_controlled_agent_max_steps_clamps_to_local_safety_limit(self):+ payload, _ = perplexity._build_agent_payload(+ "test topic",+ ("2026-05-01", "2026-06-01"),+ {"LAST30DAYS_PERPLEXITY_AGENT_MAX_STEPS": "100"},+ deep=False,+ )++ self.assertEqual(15, payload["max_steps"])++ def test_explicit_anthropic_model_gets_required_output_token_budget(self):+ payload, selection = perplexity._build_agent_payload(+ "test topic",+ ("2026-05-01", "2026-06-01"),+ {+ "LAST30DAYS_PERPLEXITY_AGENT_MODEL": "anthropic/claude-sonnet-4-6",+ "LAST30DAYS_PERPLEXITY_AGENT_MAX_OUTPUT_TOKENS": "8192",+ },+ deep=False,+ )++ self.assertEqual(8192, payload["max_output_tokens"])+ self.assertEqual(8192, selection["request"]["max_output_tokens"])++ def test_non_anthropic_model_omits_output_token_override(self):+ payload, _ = perplexity._build_agent_payload(+ "test topic",+ ("2026-05-01", "2026-06-01"),+ {},+ deep=False,+ )++ self.assertNotIn("max_output_tokens", payload)++ def test_explicit_agent_preset_is_marked_dynamic(self):+ response = _agent_response(model="openai/gpt-5.6-luna")+ with patch("lib.perplexity.http.post", return_value=response) as post:+ _, artifact = perplexity.search(+ "test topic",+ ("2026-05-01", "2026-06-01"),+ {+ "PERPLEXITY_API_KEY": "pplx-test",+ "LAST30DAYS_PERPLEXITY_AGENT_PRESET": "low",},)payload = post.call_args.args[1]- self.assertEqual("sonar-reasoning-pro", payload["model"])- self.assertEqual("high", payload["reasoning_effort"])- self.assertEqual("sonar-reasoning-pro", artifact["model"])+ self.assertEqual("low", payload["preset"])+ self.assertIn("input", payload)+ self.assertNotIn("model", payload)+ self.assertEqual("web_search", payload["tools"][0]["type"])+ self.assertEqual(10, payload["tools"][0]["max_results"])+ self.assertTrue(artifact["dynamicPreset"])+ self.assertEqual("low", artifact["preset"])+ self.assertEqual("openai/gpt-5.6-luna", artifact["servedModel"])+ self.assertEqual(perplexity.PERPLEXITY_PRESET_PROFILE, artifact["profile"])++ def test_agent_falls_back_to_message_output_when_output_text_is_missing(self):+ citations = [+ {+ "title": "Example A",+ "url": "https://example.com/a",+ "snippet": "Direct source snippet",+ }+ ]+ response = _agent_response(+ "Message-only synthesis",+ citations=citations,+ include_output_text=False,+ )+ with patch("lib.perplexity.http.post", return_value=response):+ items, artifact = perplexity.search(+ "test topic",+ ("2026-05-01", "2026-06-01"),+ {"PERPLEXITY_API_KEY": "pplx-test"},+ )++ self.assertEqual("Message-only synthesis", items[0]["snippet"])+ self.assertEqual(1, artifact["citationCount"])- def test_openrouter_fallback_uses_openrouter_models_and_annotations(self):+ def test_malformed_agent_output_returns_safe_empty_artifact(self):response = {+ "id": "agent-empty",+ "status": "completed",+ "model": "perplexity/sonar",+ "output": [{"type": "function_call", "arguments": "untrusted trace"}],+ "usage": {"total_tokens": 2},+ }+ with patch("lib.perplexity.http.post", return_value=response):+ items, artifact = perplexity.search(+ "test topic",+ ("2026-05-01", "2026-06-01"),+ {"PERPLEXITY_API_KEY": "pplx-test"},+ )++ self.assertEqual([], items)+ self.assertEqual("empty_synthesis", artifact["error"])+ self.assertEqual("perplexity/sonar", artifact["servedModel"])+ self.assertEqual(["function_call"], artifact["outputTypes"])+ self.assertNotIn("arguments", artifact)++ def test_sync_terminal_failure_keeps_safe_response_metadata(self):+ response = {+ "id": "agent-failed",+ "status": "failed",+ "error": {"message": "Provider safely rejected this request"},+ "output": [{"type": "function_call", "arguments": "raw tool trace"}],+ "usage": {"total_tokens": 7},+ }+ with patch("lib.perplexity.http.post", return_value=response):+ items, artifact = perplexity.search(+ "test topic",+ ("2026-05-01", "2026-06-01"),+ {"PERPLEXITY_API_KEY": "pplx-test"},+ )++ self.assertEqual([], items)+ self.assertEqual("failed", artifact["error"])+ self.assertEqual("agent-failed", artifact["responseId"])+ self.assertEqual("failed", artifact["status"])+ self.assertEqual("Provider safely rejected this request", artifact["agentErrorMessage"])+ self.assertEqual({"total_tokens": 7}, artifact["usage"])+ self.assertEqual(["function_call"], artifact["outputTypes"])+ self.assertNotIn("arguments", artifact)++ def test_sync_incomplete_response_keeps_safe_reason(self):+ response = {+ "id": "agent-incomplete",+ "status": "incomplete",+ "incomplete_details": {"reason": "max_output_tokens"},+ "output": [],+ "usage": {"total_tokens": 11},+ }+ with patch("lib.perplexity.http.post", return_value=response):+ items, artifact = perplexity.search(+ "test topic",+ ("2026-05-01", "2026-06-01"),+ {"PERPLEXITY_API_KEY": "pplx-test"},+ )++ self.assertEqual([], items)+ self.assertEqual("incomplete", artifact["error"])+ self.assertEqual("max_output_tokens", artifact["incompleteReason"])+ self.assertNotIn("incomplete_details", artifact)++ def test_openrouter_only_config_uses_sonar_fallback(self):+ response = {+ "id": "openrouter-1",+ "model": "perplexity/sonar-pro","choices": [{"message": {- "content": "OpenRouter synthesis",+ "content": "OpenRouter fallback synthesis","annotations": [{"url_citation": {- "url": "https://example.com/b",- "title": "Example B",+ "url": "https://example.com/openrouter",+ "title": "OpenRouter citation",}}],}}],+ "usage": {"total_tokens": 42},}- with patch("lib.perplexity.http.post", return_value=response) as post:+ with patch("lib.perplexity.http.post", return_value=response) as post, patch(+ "lib.perplexity.http.get"+ ) as get:items, artifact = perplexity.search("test topic",("2026-05-01", "2026-06-01"),{"OPENROUTER_API_KEY": "or-test"},- deep=True,)url, payload = post.call_args.args[:2]- headers = post.call_args.kwargs["headers"]self.assertEqual(perplexity.OPENROUTER_URL, url)- self.assertEqual("Bearer or-test", headers["Authorization"])- self.assertEqual("perplexity/sonar-deep-research", payload["model"])- self.assertEqual(120, post.call_args.kwargs["timeout"])+ self.assertEqual("perplexity/sonar-pro", payload["model"])+ self.assertEqual("Bearer or-test", post.call_args.kwargs["headers"]["Authorization"])+ self.assertEqual(1, post.call_args.kwargs["retries"])+ get.assert_not_called()+ self.assertEqual("openrouter", artifact["provider"])+ self.assertEqual("sonar", artifact["mode"])+ self.assertEqual("openrouter-chat-completions", artifact["endpoint"])+ self.assertEqual("OpenRouter fallback synthesis", items[0]["snippet"])+ self.assertEqual("OpenRouter citation", items[1]["title"])++ def test_openrouter_search_mode_degrades_to_sonar_fallback(self):+ response = {+ "id": "openrouter-2",+ "model": "perplexity/sonar-pro",+ "choices": [{"message": {"content": "Fallback synthesis"}}],+ }+ with patch("lib.perplexity.http.post", return_value=response) as post:+ _, artifact = perplexity.search(+ "test topic",+ ("2026-05-01", "2026-06-01"),+ {+ "OPENROUTER_API_KEY": "or-test",+ "LAST30DAYS_PERPLEXITY_MODE": "search",+ },+ )++ self.assertEqual(perplexity.OPENROUTER_URL, post.call_args.args[0])+ self.assertEqual("openrouter", artifact["provider"])+ self.assertEqual("sonar", artifact["mode"])++ def test_openrouter_deep_research_keeps_synchronous_legacy_fallback(self):+ response = {+ "id": "openrouter-deep-1",+ "model": "perplexity/sonar-deep-research",+ "choices": [{"message": {"content": "Deep fallback synthesis"}}],+ }+ with patch("lib.perplexity.http.post", return_value=response) as post, patch(+ "lib.perplexity.http.get"+ ) as get:+ items, artifact = perplexity.search(+ "test topic",+ ("2026-05-01", "2026-06-01"),+ {"OPENROUTER_API_KEY": "or-test"},+ deep=True,+ )++ self.assertEqual(perplexity.OPENROUTER_URL, post.call_args.args[0])+ self.assertEqual(+ "perplexity/sonar-deep-research",+ post.call_args.args[1]["model"],+ )+ get.assert_not_called()+ self.assertEqual("Deep fallback synthesis", items[0]["snippet"])+ self.assertTrue(artifact["deep"])+ self.assertEqual("openrouter", artifact["provider"])++ def test_openrouter_failure_keeps_typed_source_receipt(self):+ with patch(+ "lib.perplexity.http.post",+ side_effect=perplexity.http.HTTPError(+ "HTTP 429: Too Many Requests",+ status_code=429,+ ),+ ):+ items, artifact = perplexity.search(+ "test topic",+ ("2026-05-01", "2026-06-01"),+ {"OPENROUTER_API_KEY": "or-test"},+ )++ self.assertEqual([], items)self.assertEqual("openrouter", artifact["provider"])- self.assertEqual("perplexity/sonar-deep-research", artifact["model"])- self.assertEqual("Example B", items[1]["title"])+ self.assertEqual("openrouter-chat-completions", artifact["endpoint"])+ self.assertEqual(429, artifact["statusCode"])def test_search_api_mode_returns_ranked_rows_with_filters(self):response = {@@ -138,11 +419,13 @@ class PerplexityProviderTests(unittest.TestCase):url, payload = post.call_args.args[:2]self.assertEqual(perplexity.PERPLEXITY_SEARCH_URL, url)+ self.assertEqual(1, post.call_args.kwargs["retries"])self.assertEqual("test topic", payload["query"])self.assertEqual(3, payload["max_results"])self.assertEqual("low", payload["search_context_size"])self.assertEqual("US", payload["country"])self.assertEqual(["example.com", "example.org"], payload["search_domain_filter"])+ self.assertEqual(["en"], payload["search_language_filter"])self.assertEqual("05/01/2026", payload["search_after_date_filter"])self.assertEqual("06/01/2026", payload["search_before_date_filter"])self.assertNotIn("search_recency_filter", payload)@@ -179,21 +462,19 @@ class PerplexityProviderTests(unittest.TestCase):},],}- sonar_response = {- "choices": [{"message": {"content": "Sonar synthesis"}}],- "citations": ["https://example.com/a"],- "search_results": [+ agent_response = _agent_response(+ citations=[{"title": "Citation result","url": "https://example.com/a","snippet": "Citation row","date": "2026-05-15",}- ],- }+ ]+ )with patch("lib.perplexity.http.post",- side_effect=[search_response, sonar_response],+ side_effect=[search_response, agent_response],) as post:items, artifact = perplexity.search("test topic",@@ -205,14 +486,16 @@ class PerplexityProviderTests(unittest.TestCase):)self.assertEqual(perplexity.PERPLEXITY_SEARCH_URL, post.call_args_list[0].args[0])- self.assertEqual(perplexity.PERPLEXITY_URL, post.call_args_list[1].args[0])+ self.assertEqual(perplexity.PERPLEXITY_AGENT_URL, post.call_args_list[1].args[0])self.assertEqual("both", artifact["mode"])self.assertEqual(3, artifact["itemCount"])self.assertEqual("perplexity.ai", items[0]["source_domain"])urls = [item["url"] for item in items if item["url"]]self.assertEqual(["https://example.com/a", "https://example.com/unique"], urls)+ self.assertIn("agent", artifact)+ self.assertNotIn("sonar", artifact)- def test_both_mode_keeps_search_rows_when_sonar_leg_fails(self):+ def test_both_mode_keeps_search_rows_when_agent_leg_fails(self):search_response = {"id": "search-1","results": [@@ -242,35 +525,26 @@ class PerplexityProviderTests(unittest.TestCase):self.assertEqual("Raw result", items[0]["title"])self.assertEqual(1, artifact["itemCount"])- self.assertEqual("HTTPError", artifact["sonar"]["error"])- self.assertEqual(500, artifact["sonar"]["statusCode"])-- def test_direct_deep_research_uses_async_api_and_wall_timeout_config(self):- create_response = {"id": "async-1", "status": "CREATED", "created_at": 123}- complete_response = {- "id": "async-1",- "status": "COMPLETED",- "created_at": 123,- "started_at": 124,- "completed_at": 130,- "response": {- "choices": [{"message": {"content": "Deep synthesis"}}],- "citations": ["https://example.com/deep"],- "search_results": [- {- "title": "Deep citation",- "url": "https://example.com/deep",- "snippet": "Deep snippet",- }- ],- "usage": {- "total_tokens": 123,- "cost": {"total_cost": 0.12},- },- },- }- with patch("lib.perplexity.http.post", return_value=create_response) as post, \- patch("lib.perplexity.http.get", return_value=complete_response) as get:+ self.assertEqual("HTTPError", artifact["agent"]["error"])+ self.assertEqual(500, artifact["agent"]["statusCode"])++ def test_deep_research_uses_agent_background_high_preset(self):+ created = {"id": "agent-deep-1", "status": "queued"}+ completed = _agent_response(+ "Deep synthesis",+ response_id="agent-deep-1",+ citations=[+ {+ "title": "Deep citation",+ "url": "https://example.com/deep",+ "snippet": "Deep snippet",+ }+ ],+ )+ with patch("lib.perplexity.http.post", return_value=created) as post, patch(+ "lib.perplexity.http.get",+ return_value=completed,+ ) as get:items, artifact = perplexity.search("test topic",("2026-05-01", "2026-06-01"),@@ -281,36 +555,38 @@ class PerplexityProviderTests(unittest.TestCase):deep=True,)- self.assertEqual(perplexity.PERPLEXITY_ASYNC_URL, post.call_args.args[0])+ self.assertEqual(perplexity.PERPLEXITY_AGENT_URL, post.call_args.args[0])+ payload = post.call_args.args[1]+ self.assertEqual(1, post.call_args.kwargs["retries"])+ self.assertEqual("high", payload["preset"])+ self.assertTrue(payload["background"])+ self.assertNotIn("model", payload)+ tool = payload["tools"][0]+ self.assertEqual("web_search", tool["type"])+ self.assertEqual(10, tool["max_results"])+ self.assertEqual("05/01/2026", tool["filters"]["search_after_date_filter"])+ self.assertEqual("06/01/2026", tool["filters"]["search_before_date_filter"])self.assertEqual(- perplexity.PERPLEXITY_ASYNC_URL,- perplexity._provider({"PERPLEXITY_API_KEY": "pplx-test"}, deep=True)[2],+ f"{perplexity.PERPLEXITY_AGENT_URL}/agent-deep-1",+ get.call_args.args[0],)- create_payload = post.call_args.args[1]- self.assertEqual("sonar-deep-research", create_payload["request"]["model"])- self.assertTrue(create_payload["idempotency_key"].startswith("last30days:"))- self.assertEqual(f"{perplexity.PERPLEXITY_ASYNC_URL}/async-1", get.call_args.args[0])- self.assertEqual("async-sonar", artifact["endpoint"])- self.assertEqual(True, artifact["async"])- self.assertEqual(300, artifact["asyncTimeoutSeconds"])- self.assertEqual(create_payload["idempotency_key"], artifact["asyncIdempotencyKey"])- self.assertEqual(1, artifact["asyncPollCount"])- self.assertEqual("COMPLETED_REMOTE", artifact["asyncLocalStatus"])- self.assertEqual(123, artifact["asyncCreatedAt"])- self.assertEqual(124, artifact["asyncStartedAt"])- self.assertEqual(130, artifact["asyncCompletedAt"])+ self.assertEqual("agent-background", artifact["endpoint"])+ self.assertTrue(artifact["background"])+ self.assertEqual(300, artifact["backgroundTimeoutSeconds"])+ self.assertEqual(1, artifact["backgroundPollCount"])+ self.assertEqual("COMPLETED_REMOTE", artifact["backgroundLocalStatus"])+ self.assertEqual("high", artifact["preset"])+ self.assertTrue(artifact["dynamicPreset"])self.assertEqual(123, items[0]["metadata"]["usage"]["total_tokens"])- def test_direct_deep_research_timeout_returns_empty_result(self):- with patch("lib.perplexity.http.post", return_value={"id": "async-1", "status": "CREATED", "created_at": 123}), \- patch("lib.perplexity.http.get", return_value={- "id": "async-1",- "status": "IN_PROGRESS",- "created_at": 123,- "started_at": 124,- }), \- patch("lib.perplexity.time.monotonic", side_effect=[0, 0, 2, 2]), \- patch("lib.perplexity.time.sleep"):+ def test_deep_research_timeout_preserves_background_response_id(self):+ with patch(+ "lib.perplexity.http.post",+ return_value={"id": "agent-deep-1", "status": "queued"},+ ) as post, patch(+ "lib.perplexity.time.monotonic",+ side_effect=[0, 1],+ ), patch("lib.perplexity.http.get") as get:items, artifact = perplexity.search("test topic",("2026-05-01", "2026-06-01"),@@ -321,189 +597,195 @@ class PerplexityProviderTests(unittest.TestCase):deep=True,)+ post.assert_called_once()+ get.assert_not_called()self.assertEqual([], items)self.assertEqual("timeout", artifact["error"])- self.assertEqual("async-1", artifact["asyncRequestId"])- self.assertEqual("IN_PROGRESS", artifact["asyncStatus"])- self.assertEqual(1, artifact["asyncTimeoutSeconds"])- self.assertEqual(1, artifact["asyncPollCount"])- self.assertEqual("PENDING_REMOTE", artifact["asyncLocalStatus"])- self.assertEqual(123, artifact["asyncCreatedAt"])- self.assertEqual(124, artifact["asyncStartedAt"])-- def test_direct_deep_research_failed_status_returns_failure_artifact(self):- with patch("lib.perplexity.http.post", return_value={"id": "async-1", "status": "CREATED"}), \- patch("lib.perplexity.http.get", return_value={- "id": "async-1",- "status": "FAILED",- "failed_at": 130,- "error_message": "provider failure",- }):+ self.assertEqual("agent-deep-1", artifact["responseId"])+ self.assertEqual("queued", artifact["backgroundStatus"])+ self.assertEqual(1, artifact["backgroundTimeoutSeconds"])+ self.assertEqual(0, artifact["backgroundPollCount"])+ self.assertEqual("PENDING_REMOTE", artifact["backgroundLocalStatus"])++ def test_deep_research_nonterminal_poll_after_deadline_is_timeout(self):+ with patch(+ "lib.perplexity.http.post",+ return_value={"id": "agent-deep-1", "status": "queued"},+ ), patch(+ "lib.perplexity.http.get",+ return_value={"id": "agent-deep-1", "status": "queued"},+ ) as get, patch(+ "lib.perplexity.time.monotonic",+ side_effect=[0.0, 0.5, 1.5],+ ):items, artifact = perplexity.search("test topic",("2026-05-01", "2026-06-01"),- {"PERPLEXITY_API_KEY": "pplx-test"},+ {+ "PERPLEXITY_API_KEY": "pplx-test",+ "LAST30DAYS_PERPLEXITY_DEEP_TIMEOUT_SECONDS": "1",+ },deep=True,)self.assertEqual([], items)- self.assertEqual("failed", artifact["error"])- self.assertEqual("async-1", artifact["asyncRequestId"])- self.assertEqual("FAILED", artifact["asyncStatus"])- self.assertEqual("FAILED_REMOTE", artifact["asyncLocalStatus"])- self.assertEqual(130, artifact["asyncFailedAt"])- self.assertEqual("provider failure", artifact["asyncErrorMessage"])-- def test_direct_deep_research_poll_error_preserves_async_id(self):- with patch("lib.perplexity.http.post", return_value={- "id": "async-1",- "status": "CREATED",- "created_at": 123,- }), \- patch("lib.perplexity.http.get", side_effect=perplexity.http.HTTPError(- "HTTP 429: Too Many Requests",- status_code=429,- )):+ self.assertEqual("timeout", artifact["error"])+ self.assertEqual("PENDING_REMOTE", artifact["backgroundLocalStatus"])+ self.assertEqual(1, artifact["backgroundPollCount"])+ self.assertEqual(1.0, get.call_args.kwargs["deadline_monotonic"])++ def test_deep_research_poll_retry_deadline_is_timeout_not_poll_error(self):+ with patch(+ "lib.perplexity.http.post",+ return_value={"id": "agent-deep-1", "status": "queued"},+ ), patch(+ "lib.perplexity.http.get",+ side_effect=perplexity.http.DeadlineExceeded(),+ ), patch(+ "lib.perplexity.time.monotonic",+ side_effect=[0.0, 0.5],+ ):items, artifact = perplexity.search("test topic",("2026-05-01", "2026-06-01"),- {"PERPLEXITY_API_KEY": "pplx-test"},+ {+ "PERPLEXITY_API_KEY": "pplx-test",+ "LAST30DAYS_PERPLEXITY_DEEP_TIMEOUT_SECONDS": "1",+ },deep=True,)self.assertEqual([], items)- self.assertEqual("poll_error", artifact["error"])- self.assertEqual("async-1", artifact["asyncRequestId"])- self.assertEqual("CREATED", artifact["asyncStatus"])- self.assertEqual("POLL_ERROR", artifact["asyncLocalStatus"])- self.assertEqual(1, artifact["asyncPollCount"])- self.assertEqual(429, artifact["asyncPollStatusCode"])-- def test_direct_deep_research_malformed_completed_preserves_async_id(self):- with patch("lib.perplexity.http.post", return_value={- "id": "async-1",- "status": "CREATED",- "created_at": 123,- }), \- patch("lib.perplexity.http.get", return_value={- "id": "async-1",- "status": "COMPLETED",- "created_at": 123,- "completed_at": 130,- "response": None,- }):+ self.assertEqual("timeout", artifact["error"])+ self.assertEqual("PENDING_REMOTE", artifact["backgroundLocalStatus"])+ self.assertEqual(1, artifact["backgroundPollCount"])++ def test_deep_research_early_transport_timeout_is_poll_error(self):+ with patch(+ "lib.perplexity.http.post",+ return_value={"id": "agent-deep-1", "status": "queued"},+ ), patch(+ "lib.perplexity.http.get",+ side_effect=perplexity.http.HTTPError(+ "URL Error: timed out",+ outcome_state=perplexity.health.TIMEOUT,+ ),+ ), patch(+ "lib.perplexity.time.monotonic",+ side_effect=[0.0, 10.0, 10.0],+ ):items, artifact = perplexity.search("test topic",("2026-05-01", "2026-06-01"),- {"PERPLEXITY_API_KEY": "pplx-test"},+ {+ "PERPLEXITY_API_KEY": "pplx-test",+ "LAST30DAYS_PERPLEXITY_DEEP_TIMEOUT_SECONDS": "600",+ },deep=True,)self.assertEqual([], items)- self.assertEqual("failed", artifact["error"])- self.assertEqual("async-1", artifact["asyncRequestId"])- self.assertEqual("COMPLETED", artifact["asyncStatus"])- self.assertEqual("FAILED_REMOTE", artifact["asyncLocalStatus"])- self.assertEqual(1, artifact["asyncPollCount"])- self.assertEqual(130, artifact["asyncCompletedAt"])- self.assertEqual(- "Async Deep Research completed without response",- artifact["asyncErrorMessage"],- )+ self.assertEqual("poll_error", artifact["error"])+ self.assertEqual("POLL_ERROR", artifact["backgroundLocalStatus"])- def test_direct_deep_research_empty_choices_preserves_async_id(self):- with patch("lib.perplexity.http.post", return_value={- "id": "async-1",- "status": "CREATED",- "created_at": 123,- }) as post, \- patch("lib.perplexity.http.get", return_value={- "id": "async-1",- "status": "COMPLETED",- "created_at": 123,- "completed_at": 130,- "response": {- "choices": [],- "usage": {"total_tokens": 321},- },- }):+ def test_deep_research_terminal_poll_after_deadline_is_timeout(self):+ with patch(+ "lib.perplexity.http.post",+ return_value={"id": "agent-deep-1", "status": "queued"},+ ), patch(+ "lib.perplexity.http.get",+ return_value={"id": "agent-deep-1", "status": "completed"},+ ), patch(+ "lib.perplexity.time.monotonic",+ side_effect=[0.0, 0.5, 1.5],+ ):items, artifact = perplexity.search("test topic",("2026-05-01", "2026-06-01"),- {"PERPLEXITY_API_KEY": "pplx-test"},+ {+ "PERPLEXITY_API_KEY": "pplx-test",+ "LAST30DAYS_PERPLEXITY_DEEP_TIMEOUT_SECONDS": "1",+ },deep=True,)self.assertEqual([], items)- self.assertEqual("empty_choices", artifact["error"])- self.assertEqual("async-1", artifact["asyncRequestId"])- self.assertEqual("COMPLETED", artifact["asyncStatus"])- self.assertEqual("COMPLETED_REMOTE", artifact["asyncLocalStatus"])- self.assertEqual(1, artifact["asyncPollCount"])- self.assertEqual(130, artifact["asyncCompletedAt"])- self.assertEqual(- post.call_args.args[1]["idempotency_key"],- artifact["asyncIdempotencyKey"],- )- self.assertEqual(321, artifact["usage"]["total_tokens"])- self.assertEqual(- "Async Deep Research completed without choices",- artifact["asyncErrorMessage"],- )-- def test_direct_deep_research_empty_synthesis_preserves_async_id(self):- with patch("lib.perplexity.http.post", return_value={- "id": "async-1",- "status": "CREATED",- "created_at": 123,- }) as post, \- patch("lib.perplexity.http.get", return_value={- "id": "async-1",- "status": "COMPLETED",- "created_at": 123,- "completed_at": 130,- "response": {- "choices": [{"message": {"content": ""}}],- },- }):- items, artifact = perplexity.search(+ self.assertEqual("timeout", artifact["error"])+ self.assertEqual("completed", artifact["backgroundStatus"])+ self.assertEqual("PENDING_REMOTE", artifact["backgroundLocalStatus"])++ def test_deep_research_terminal_failures_are_recorded(self):+ for status in ("failed", "cancelled", "incomplete"):+ response = {+ "id": "agent-deep-1",+ "status": status,+ "model": "openai/gpt-5.6-sol",+ "usage": {"total_tokens": 17},+ "output": [{"type": "message", "content": []}],+ }+ if status == "incomplete":+ response["incomplete_details"] = {"reason": "max_output_tokens"}+ with self.subTest(status=status), patch(+ "lib.perplexity.http.post",+ return_value=response,+ ) as post, patch("lib.perplexity.http.get") as get:+ items, artifact = perplexity.search(+ "test topic",+ ("2026-05-01", "2026-06-01"),+ {"PERPLEXITY_API_KEY": "pplx-test"},+ deep=True,+ )++ post.assert_called_once()+ get.assert_not_called()+ self.assertEqual([], items)+ self.assertEqual("failed", artifact["error"])+ self.assertEqual(status, artifact["backgroundStatus"])+ self.assertEqual("TERMINAL_REMOTE", artifact["backgroundLocalStatus"])+ self.assertEqual("openai/gpt-5.6-sol", artifact["servedModel"])+ self.assertEqual({"total_tokens": 17}, artifact["usage"])+ self.assertEqual(["message"], artifact["outputTypes"])+ if status == "incomplete":+ self.assertEqual("max_output_tokens", artifact["incompleteReason"])++ def test_deep_research_logs_safe_receipt_for_cli_consumers(self):+ response = {+ "id": "agent-deep-1",+ "status": "incomplete",+ "model": "openai/gpt-5.6-sol",+ "incomplete_details": {"reason": "max_output_tokens"},+ }+ with patch("lib.perplexity.http.post", return_value=response), patch(+ "lib.perplexity._log",+ ) as logger:+ perplexity.search("test topic",("2026-05-01", "2026-06-01"),{"PERPLEXITY_API_KEY": "pplx-test"},deep=True,)- self.assertEqual([], items)- self.assertEqual("empty_synthesis", artifact["error"])- self.assertEqual("async-1", artifact["asyncRequestId"])- self.assertEqual("COMPLETED", artifact["asyncStatus"])- self.assertEqual("COMPLETED_REMOTE", artifact["asyncLocalStatus"])- self.assertEqual(1, artifact["asyncPollCount"])- self.assertEqual(130, artifact["asyncCompletedAt"])- self.assertEqual(- post.call_args.args[1]["idempotency_key"],- artifact["asyncIdempotencyKey"],- )- self.assertEqual(- "Async Deep Research completed with empty synthesis",- artifact["asyncErrorMessage"],+ receipt = next(+ call.args[0]+ for call in logger.call_args_list+ if call.args and call.args[0].startswith("Deep Research receipt:"))+ self.assertIn("model=openai/gpt-5.6-sol", receipt)+ self.assertIn("response_id=agent-deep-1", receipt)+ self.assertIn("provider_status=incomplete", receipt)+ self.assertIn("incomplete_reason=max_output_tokens", receipt)- def test_direct_deep_research_malformed_choice_preserves_async_id(self):- with patch("lib.perplexity.http.post", return_value={- "id": "async-1",- "status": "CREATED",- "created_at": 123,- }) as post, \- patch("lib.perplexity.http.get", return_value={- "id": "async-1",- "status": "COMPLETED",- "created_at": 123,- "completed_at": 130,- "response": {- "choices": [None],- },- }):+ def test_deep_research_poll_error_preserves_response_id(self):+ with patch(+ "lib.perplexity.http.post",+ return_value={"id": "agent-deep-1", "status": "queued"},+ ), patch(+ "lib.perplexity.http.get",+ side_effect=perplexity.http.HTTPError(+ "HTTP 429: Too Many Requests",+ status_code=429,+ ),+ ):items, artifact = perplexity.search("test topic",("2026-05-01", "2026-06-01"),@@ -512,14 +794,12 @@ class PerplexityProviderTests(unittest.TestCase):)self.assertEqual([], items)- self.assertEqual("empty_synthesis", artifact["error"])- self.assertEqual("async-1", artifact["asyncRequestId"])- self.assertEqual("COMPLETED", artifact["asyncStatus"])- self.assertEqual("COMPLETED_REMOTE", artifact["asyncLocalStatus"])- self.assertEqual(- post.call_args.args[1]["idempotency_key"],- artifact["asyncIdempotencyKey"],- )+ self.assertEqual("poll_error", artifact["error"])+ self.assertEqual("agent-deep-1", artifact["responseId"])+ self.assertEqual("queued", artifact["backgroundStatus"])+ self.assertEqual("POLL_ERROR", artifact["backgroundLocalStatus"])+ self.assertEqual(1, artifact["backgroundPollCount"])+ self.assertEqual(429, artifact["backgroundPollStatusCode"])def test_missing_keys_skip_without_http(self):with patch("lib.perplexity.http.post") as post:@@ -532,3 +812,7 @@ class PerplexityProviderTests(unittest.TestCase):post.assert_not_called()self.assertEqual([], items)self.assertEqual({}, artifact)+++if __name__ == "__main__":+ unittest.main()diff --git a/tests/test_pipeline_v3.py b/tests/test_pipeline_v3.pyindex f0b13879..82b4c592 100644--- a/tests/test_pipeline_v3.py+++ b/tests/test_pipeline_v3.py@@ -3,6 +3,7 @@ import unittestfrom unittest.mock import patchfrom lib import health+from lib import fanoutfrom lib import httpfrom lib import pipelinefrom lib import schema@@ -250,6 +251,14 @@ class PipelineV3Tests(unittest.TestCase):class TestSourceFetchCap(unittest.TestCase):+ def test_paid_budget_rejects_non_owner_before_owner_claims(self):+ paid_budget = pipeline.PaidSourceBudget(owner="main")++ self.assertFalse(paid_budget.try_consume(1, claimant="peer"))+ self.assertEqual(0, paid_budget.used)+ self.assertTrue(paid_budget.try_consume(1, claimant="main"))+ self.assertEqual(1, paid_budget.used)+"""X source fetch count must be capped by MAX_SOURCE_FETCHES."""def test_x_capped_in_max_source_fetches(self):@@ -261,6 +270,50 @@ class TestSourceFetchCap(unittest.TestCase):self.assertIn("jobs", pipeline.MAX_SOURCE_FETCHES)self.assertEqual(pipeline.MAX_SOURCE_FETCHES["jobs"], 1)+ def test_perplexity_paid_call_cap_cannot_be_raised_by_generic_override(self):+ self.assertEqual(+ 1,+ pipeline._source_fetch_cap(+ "perplexity",+ {"_max_source_fetches": 10},+ ),+ )+ self.assertEqual(+ 0,+ pipeline._source_fetch_cap(+ "perplexity",+ {"_max_source_fetches": 0},+ ),+ )++ def test_deep_research_lane_is_isolated_and_does_not_replace_primary(self):+ primary = schema.SubQuery(+ label="primary",+ search_query="narrow angle",+ ranking_query="narrow angle",+ sources=["reddit", "grounding", "perplexity"],+ )+ plan = schema.QueryPlan(+ intent="general",+ freshness_mode="balanced_recent",+ cluster_mode="story",+ raw_topic="whole topic",+ subqueries=[primary],+ source_weights={"reddit": 1.0, "grounding": 1.0, "perplexity": 1.0},+ )++ pipeline._ensure_perplexity_in_plan(+ plan,+ "whole topic",+ ["reddit", "grounding", "perplexity"],+ force=True,+ )++ self.assertEqual("primary", plan.subqueries[0].label)+ self.assertEqual(["reddit", "grounding"], plan.subqueries[0].sources)+ self.assertEqual("deep-research", plan.subqueries[-1].label)+ self.assertEqual(["perplexity"], plan.subqueries[-1].sources)+def test_cap_logic_limits_source_submissions(self):"""Verify the cap logic skips submissions beyond the limit."""subquery_sources = [@@ -335,6 +388,196 @@ class TestSourceFetchCap(unittest.TestCase):self.assertEqual([], x_calls)self.assertGreater(len(reddit_calls), 0)+ @patch("lib.pipeline._retrieve_stream")+ def test_deep_research_subquery_fanout_submits_once(self, mock_retrieve):+ mock_retrieve.return_value = ([], {})+ plan = {+ "intent": "comparison",+ "freshness_mode": "balanced_recent",+ "cluster_mode": "debate",+ "subqueries": [+ {+ "label": f"angle-{index}",+ "search_query": f"topic angle {index}",+ "ranking_query": f"topic angle {index}",+ "sources": ["perplexity"],+ }+ for index in range(3)+ ],+ "source_weights": {"perplexity": 1.0},+ }++ pipeline.run(+ topic="whole topic",+ config={+ "LAST30DAYS_REASONING_PROVIDER": "gemini",+ "PERPLEXITY_API_KEY": "pplx-test",+ "_deep_research": True,+ "_max_source_fetches": 10,+ },+ depth="default",+ requested_sources=["reddit", "perplexity"],+ mock=True,+ external_plan=plan,+ )++ perplexity_calls = [+ call+ for call in mock_retrieve.call_args_list+ if call.kwargs.get("source") == "perplexity"+ ]+ self.assertEqual(1, len(perplexity_calls))+ self.assertEqual(+ "whole topic",+ perplexity_calls[0].kwargs["subquery"].search_query,+ )++ @patch("lib.pipeline._retrieve_stream")+ def test_normal_perplexity_subquery_fanout_submits_once(self, mock_retrieve):+ mock_retrieve.return_value = ([], {})+ plan = {+ "intent": "comparison",+ "freshness_mode": "balanced_recent",+ "cluster_mode": "debate",+ "subqueries": [+ {+ "label": f"angle-{index}",+ "search_query": f"topic angle {index}",+ "ranking_query": f"topic angle {index}",+ "sources": ["perplexity"],+ }+ for index in range(4)+ ],+ "source_weights": {"perplexity": 1.0},+ }++ pipeline.run(+ topic="whole topic",+ config={+ "LAST30DAYS_REASONING_PROVIDER": "gemini",+ "PERPLEXITY_API_KEY": "pplx-test",+ "_max_source_fetches": 10,+ },+ depth="default",+ requested_sources=["perplexity"],+ mock=True,+ external_plan=plan,+ )++ perplexity_calls = [+ call+ for call in mock_retrieve.call_args_list+ if call.kwargs.get("source") == "perplexity"+ ]+ self.assertEqual(1, len(perplexity_calls))+ self.assertEqual(+ "whole topic",+ perplexity_calls[0].kwargs["subquery"].search_query,+ )++ @patch("lib.pipeline._retrieve_stream")+ def test_shared_paid_budget_caps_competitor_subruns(self, mock_retrieve):+ mock_retrieve.return_value = ([], {})+ paid_budget = pipeline.PaidSourceBudget()+ plan = {+ "intent": "general",+ "freshness_mode": "balanced_recent",+ "cluster_mode": "story",+ "subqueries": [+ {+ "label": "primary",+ "search_query": "entity angle",+ "ranking_query": "entity angle",+ "sources": ["perplexity"],+ }+ ],+ "source_weights": {"perplexity": 1.0},+ }++ for entity in ("main", "peer-a", "peer-b"):+ pipeline.run(+ topic=entity,+ config={+ "LAST30DAYS_REASONING_PROVIDER": "gemini",+ "PERPLEXITY_API_KEY": "pplx-test",+ "_perplexity_paid_budget": paid_budget,+ },+ depth="quick",+ requested_sources=["perplexity"],+ mock=True,+ external_plan=plan,+ internal_subrun=True,+ )++ perplexity_calls = [+ call+ for call in mock_retrieve.call_args_list+ if call.kwargs.get("source") == "perplexity"+ ]+ self.assertEqual(1, len(perplexity_calls))+ self.assertEqual(1, paid_budget.used)++ @patch("lib.pipeline._retrieve_stream")+ def test_shared_paid_budget_is_reserved_for_main_competitor_topic(+ self,+ mock_retrieve,+ ):+ mock_retrieve.return_value = ([], {})+ paid_budget = pipeline.PaidSourceBudget(owner="main")+ barrier = threading.Barrier(3)+ plan = {+ "intent": "general",+ "freshness_mode": "balanced_recent",+ "cluster_mode": "story",+ "subqueries": [+ {+ "label": "primary",+ "search_query": "entity angle",+ "ranking_query": "entity angle",+ "sources": ["perplexity"],+ }+ ],+ "source_weights": {"perplexity": 1.0},+ }++ def run_entity(entity):+ barrier.wait()+ return pipeline.run(+ topic=entity,+ config={+ "LAST30DAYS_REASONING_PROVIDER": "gemini",+ "PERPLEXITY_API_KEY": "pplx-test",+ "_perplexity_paid_budget": paid_budget,+ },+ depth="quick",+ requested_sources=["perplexity"],+ mock=True,+ external_plan=plan,+ internal_subrun=True,+ )++ results = fanout.run_competitor_fanout(+ main_topic="main",+ main_runner=lambda: run_entity("main"),+ competitors=["peer-a", "peer-b"],+ competitor_runner=run_entity,+ )++ perplexity_calls = [+ call+ for call in mock_retrieve.call_args_list+ if call.kwargs.get("source") == "perplexity"+ ]+ self.assertEqual(1, len(perplexity_calls))+ self.assertEqual("main", perplexity_calls[0].kwargs["topic"])+ self.assertEqual(1, paid_budget.used)+ for entity, report in results[1:]:+ receipt = report.artifacts["paid_source_budget"]["perplexity"]+ self.assertEqual("skipped-budget", receipt["state"])+ self.assertFalse(receipt["attempted"])+ self.assertEqual("main", receipt["owner"])+ self.assertEqual(entity, receipt["claimant"])+class TestRateLimitSharing(unittest.TestCase):"""429 signals should be shared across subqueries."""@@ -1361,6 +1604,41 @@ class TestThinSourceRetry(unittest.TestCase):)mock_retrieve.assert_not_called()+ def test_perplexity_is_not_retried_when_results_are_thin(self):+ plan = schema.QueryPlan(+ intent="general",+ freshness_mode="balanced_recent",+ cluster_mode="story",+ raw_topic="AI safety",+ subqueries=[+ schema.SubQuery(+ label="primary",+ search_query="AI safety",+ ranking_query="AI safety",+ sources=["perplexity"],+ )+ ],+ source_weights={"perplexity": 1.0},+ )+ bundle = schema.RetrievalBundle()++ with patch("lib.pipeline._retrieve_stream") as mock_retrieve:+ pipeline._retry_thin_sources(+ topic="AI safety",+ bundle=bundle,+ plan=plan,+ config={},+ depth="default",+ date_range=("2026-02-15", "2026-03-17"),+ runtime=_make_runtime(),+ mock=False,+ rate_limited_sources=set(),+ rate_limit_lock=threading.Lock(),+ settings=pipeline.DEPTH_SETTINGS["default"],+ )++ mock_retrieve.assert_not_called()+class TestErrorCleanup(unittest.TestCase):"""Source errors should be cleared when the source has items from other subqueries."""@@ -1713,6 +1991,37 @@ class TestExcludeSources(unittest.TestCase):class TestPerplexityAvailability(unittest.TestCase):+ def test_agent_background_failure_uses_safe_provider_detail(self):+ outcome = pipeline._legacy_artifact_outcome(+ "perplexity",+ {+ "error": "failed",+ "backgroundErrorMessage": "Provider reported an incomplete run",+ },+ )++ self.assertEqual(health.ERROR, outcome["state"])+ self.assertEqual("Provider reported an incomplete run", outcome["detail"])++ def test_agent_background_poll_429_is_rate_limited(self):+ outcome = pipeline._legacy_artifact_outcome(+ "perplexity",+ {+ "error": "poll_error",+ "backgroundPollError": "HTTP 429: Too Many Requests",+ "backgroundPollStatusCode": 429,+ },+ )++ self.assertEqual(health.RATE_LIMITED, outcome["state"])+ self.assertEqual("HTTP 429: Too Many Requests", outcome["detail"])++ def test_perplexity_source_available_with_openrouter_fallback(self):+ sources = pipeline.available_sources(+ {"OPENROUTER_API_KEY": "test-key", "INCLUDE_SOURCES": "perplexity"}+ )+ self.assertIn("perplexity", sources)+def test_perplexity_source_not_available_with_direct_key_without_opt_in(self):sources = pipeline.available_sources({"PERPLEXITY_API_KEY": "test-key"})self.assertNotIn("perplexity", sources)diff --git a/tests/test_render_v3.py b/tests/test_render_v3.pyindex 3a2e6ba4..83a386f0 100644--- a/tests/test_render_v3.py+++ b/tests/test_render_v3.py@@ -370,7 +370,7 @@ class OutputEnvelopeTests(unittest.TestCase):return schema.SourceItem(item_id=item_id,source="perplexity",- title=f"Perplexity Sonar Pro: test topic ({item_id})",+ title=f"Perplexity Agent: test topic ({item_id})",body="AI synthesis body.",url="",container="perplexity.ai",@@ -1654,7 +1654,7 @@ class TestSourceUrlsAreClickable(unittest.TestCase):empty_url_item = schema.SourceItem(item_id="i3",source="perplexity",- title="Perplexity Sonar Pro: test topic",+ title="Perplexity Agent: test topic",body="AI synthesis body.",url="",container="perplexity.ai",diff --git a/tests/test_source_outcomes.py b/tests/test_source_outcomes.pyindex 98f1f69f..27bbca48 100644--- a/tests/test_source_outcomes.py+++ b/tests/test_source_outcomes.py@@ -339,6 +339,91 @@ def test_pipeline_records_clean_empty_source_as_no_results():assert "x" not in report.errors_by_source+def _perplexity_plan():+ return {+ "intent": "general",+ "freshness_mode": "balanced_recent",+ "cluster_mode": "story",+ "subqueries": [+ {+ "label": "primary",+ "search_query": "test topic",+ "ranking_query": "test topic",+ "sources": ["perplexity"],+ }+ ],+ "source_weights": {"perplexity": 1.0},+ }+++def test_pipeline_records_both_mode_semantic_leg_failure_as_partial():+ raw_item = {+ "id": "PXS1",+ "title": "Search result",+ "url": "https://example.com/result",+ "snippet": "Raw search evidence",+ "date": "2026-08-10",+ "relevance": 0.8,+ "why_relevant": "Perplexity Search result",+ "engagement": {},+ }+ artifact = {+ "mode": "both",+ "search": {"mode": "search"},+ "agent": {+ "error": "failed",+ "agentErrorMessage": "Provider rejected synthesis",+ },+ "itemCount": 1,+ }+ with patch("lib.pipeline._retrieve_stream_impl", return_value=([raw_item], artifact)):+ report = pipeline.run(+ topic="test topic",+ config={+ "LAST30DAYS_REASONING_PROVIDER": "gemini",+ "PERPLEXITY_API_KEY": "pplx-test",+ },+ depth="quick",+ requested_sources=["perplexity"],+ mock=True,+ external_plan=_perplexity_plan(),+ )++ outcome = report.source_status["perplexity"]+ assert outcome.state == schema.PARTIAL+ assert outcome.items_returned == 1+ assert outcome.detail == "agent leg: Provider rejected synthesis"+++def test_pipeline_records_both_mode_semantic_failure_without_items():+ artifact = {+ "mode": "both",+ "search": {"mode": "search"},+ "agent": {+ "error": "failed",+ "agentErrorMessage": "Provider rejected synthesis",+ },+ "itemCount": 0,+ }+ with patch("lib.pipeline._retrieve_stream_impl", return_value=([], artifact)):+ report = pipeline.run(+ topic="test topic",+ config={+ "LAST30DAYS_REASONING_PROVIDER": "gemini",+ "PERPLEXITY_API_KEY": "pplx-test",+ },+ depth="quick",+ requested_sources=["perplexity"],+ mock=True,+ external_plan=_perplexity_plan(),+ )++ outcome = report.source_status["perplexity"]+ assert outcome.state == health.ERROR+ assert outcome.items_returned == 0+ assert outcome.detail == "agent leg: Provider rejected synthesis"++def test_pipeline_preserves_typed_http_failure():plan = {"intent": "general",