prompture 1.13.5.dev1__tar.gz → 1.13.5.dev3__tar.gz

{prompture-1.13.5.dev1 → prompture-1.13.5.dev3}/.env.copy

@@ -252,6 +252,12 @@ PROMPTURE_SEARCH_PROVIDERS=
 PROMPTURE_FETCH_BACKENDS=
 # Allow tools to reach private/loopback addresses (off by default).
 PROMPTURE_WEB_ALLOW_PRIVATE=
+# Local cache for search / fetch / reader results: disk (default, shared
+# across processes), memory (this process only) or off. Lifetimes depend on
+# the content: minutes for weather/prices/news, days for papers/transcripts.
+PROMPTURE_WEB_CACHE=
+# Where the disk cache lives (default ~/.prompture/cache/web_cache.db).
+PROMPTURE_WEB_CACHE_PATH=
 
 # ─── Media understanding (transcripts / summaries) ───────────────────────────
 # Uses the first configured STT key: GROQ_API_KEY ▸ OPENAI_API_KEY ▸

{prompture-1.13.5.dev1 → prompture-1.13.5.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 1.13.5.dev1
+Version: 1.13.5.dev3
 Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
 Author-email: Juan Denis <juan@vene.co>
 License-Expression: MIT
@@ -162,6 +162,39 @@ print(person.name)  # Maria
 > | `ollama/llama3.1:8b`, … (local) | no extra needed | — (set `OLLAMA_HOST` if non-default) |
 > | everything in one go | `pip install "prompture[all]"` | provider-specific |
 
+## Agents That Can Search, Read, Watch and Listen
+
+Prompture also gives agents working capabilities. **Web search and reading
+need no API key at all**; keys only raise their limits and quality. Model
+calls, transcription and some packs use the keys you already have, and
+`prompture doctor` tells you exactly what's missing.
+
+```python
+from prompture import Agent
+
+agent = Agent(
+    "openai/gpt-4o-mini",
+    tools=["web:all", "pack:dev", "mcp:exa"],   # search, read any URL, transcribe, GitHub/HN/arXiv, MCP
+    system_prompt="Cite every fact with a URL you opened.",
+)
+print(agent.run("Summarize https://youtu.be/<id> and find related papers").output)
+```
+
+```bash
+prompture doctor                               # what works on this machine and how to fix the rest
+prompture research "What changed in Python 3.13?" --depth quick   # cited multi-source report
+prompture transcribe talk.mp3 --summary        # timestamped transcript + key points
+prompture mcp add --preset exa                 # mount MCP servers by name
+prompture skill install                        # teach your coding agent all of this
+```
+
+- **Web:** keyless search, fetch and readers for YouTube, GitHub, Hacker News, arXiv, Wikipedia, feeds and podcasts
+- **Fails over instead of failing:** search, fetch and the readers try the next backend on auth, quota or rate-limit errors and tell you which one served the result
+- **Cached locally:** repeat searches and static pages come back instantly; weather, prices and news expire in minutes, papers and transcripts in days
+- **Safe by default:** public URLs only, size caps, secret scrubbing, and audio never goes to a second provider without your consent
+
+Full guide: [Capabilities](#capabilities).
+
 ## Prompture Desk: Usage in Your Tray
 
 **See what your LLM calls cost, live, from your tray.** [Prompture Desk](https://github.com/jhd3197/Prompture-Desk) tracks tokens and spend per provider and project, rate-limit headroom, balances, and your coding tools (Claude Code, Codex, …). Windows, macOS and Linux.
@@ -194,8 +227,7 @@ No setup: Desk runs `prompture companion` (Prompture 1.13+) on localhost for you
 **Agents, tools, RAG**
 - Stateful conversations with sync + async support
 - Function calling and streaming across providers, with prompt-based simulation for models without native tool use
-- Drop-in tools: sandboxed `python_execute` (Tukuy), keyless `web_search` / `web_fetch` / `read_url` (YouTube, GitHub, HN, arXiv, Wikipedia, feeds, podcasts) — see [Capabilities](#capabilities)
-- Mount tools by name: `tools=["web:all", "mcp:exa", "pack:finance", "cli:gh"]`; `ResearchAgent` for cited multi-source research
+- Drop-in tools: sandboxed `python_execute` (Tukuy) plus the [capability layer](#capabilities) below
 - `DeepAgent` with planning, virtual filesystem, sub-agents, and auto-summarization — no LangChain
 - Full RAG stack — loaders, chunkers, vector stores, hybrid dense+BM25 retrieval, end-to-end `RAGPipeline` — see [RAG](#rag)
 
@@ -204,8 +236,16 @@ No setup: Desk runs `prompture companion` (Prompture 1.13+) on localhost for you
 - `RefusalDetector` / `RefusalEvaluator` for cross-provider alignment scoring
 - `generate_qa_dataset()` — synthetic JSONL datasets ready for Unsloth, Axolotl, TRL
 
-**Ops**
+**Capabilities** — see [Capabilities](#capabilities)
+- Keyless `web_search`, `web_fetch` and `read_url` (YouTube, GitHub, HN, arXiv, Wikipedia, feeds, podcasts), with failover across keyed providers
+- Local web cache with content-aware lifetimes: minutes for weather, prices and news, days for papers and transcripts
+- `transcribe` / `summarize_media` for video, podcasts and audio, with timestamped key points
+- `ResearchAgent` / `prompture research` — cited multi-source reports within fetch, token, cost and time budgets
+- MCP hub, wrapped CLI tools (`gh`, `yt-dlp`) and domain packs (finance, news, dev, places), mounted by name: `tools=["mcp:exa", "pack:finance", "cli:gh"]`
 - `prompture doctor` — what works on this machine (providers, tools, media, MCP servers, binaries), which backend is active, and the exact fix for anything that isn't
+- `prompture setup` with an owner-only credential store and profiles; `prompture skill install` teaches coding agents to use all of it
+
+**Ops**
 - Resilient routing — `resilient()` retries transient errors, honors `Retry-After`, rotates API keys, trips circuit breakers and fails over across models; every response records who served it — see [Resilient Routing](#resilient-routing)
 - [Prompture Desk](#prompture-desk-usage-in-your-tray) — desktop tray app: usage per provider and project, rate limits and balances, live calls
 - [prompture-hub](#prompture-hub-gateway--dashboard) — optional companion app: web dashboard, scoped per-app keys, spend caps and per-call metering (`pip install prompture[hub]`)
@@ -2103,6 +2143,27 @@ agent = Agent("openai/gpt-4o", tools=["web:all"])
   refused, redirects are re-checked per hop, bodies are size-capped and
   challenge pages move to the next backend.
 
+**Local cache.** Results are cached in `~/.prompture/cache/web_cache.db`, so a
+repeated search or page comes back instantly, even from another process. Each
+entry lives as long as that kind of content stays true:
+
+| Content | Lifetime |
+|---|---|
+| Searches about weather, prices, scores, news, "today", or `recency_days <= 1` | 10 min |
+| Fast-moving pages (Hacker News, Reddit, X, status pages), GitHub issues/PRs | 10 min |
+| Feeds | 15 min |
+| Platform search (GitHub, HN, arXiv, YouTube) | 30 min |
+| Ordinary pages / searches within `recency_days <= 7` | 1 h |
+| Other searches | 6 h |
+| Wikipedia, podcast episodes | 1 day |
+| Papers, PDFs, DOIs, commit-pinned GitHub files, YouTube transcripts | 7 days |
+
+Cached results say so (`route["cached"]`, `cache_age_s`, and "cached 3 min
+ago" in the Markdown footer). Errors and empty results are never stored. Pass
+`use_cache=False` or `cache_ttl=<seconds>` per call, set
+`PROMPTURE_WEB_CACHE=memory|off` to change the store, and
+`clear_web_cache()` or `prompture reset` to empty it.
+
 ### Media understanding: transcripts and summaries
 
 ```python

{prompture-1.13.5.dev1 → prompture-1.13.5.dev3}/README.md

@@ -45,6 +45,39 @@ print(person.name)  # Maria
 > | `ollama/llama3.1:8b`, … (local) | no extra needed | — (set `OLLAMA_HOST` if non-default) |
 > | everything in one go | `pip install "prompture[all]"` | provider-specific |
 
+## Agents That Can Search, Read, Watch and Listen
+
+Prompture also gives agents working capabilities. **Web search and reading
+need no API key at all**; keys only raise their limits and quality. Model
+calls, transcription and some packs use the keys you already have, and
+`prompture doctor` tells you exactly what's missing.
+
+```python
+from prompture import Agent
+
+agent = Agent(
+    "openai/gpt-4o-mini",
+    tools=["web:all", "pack:dev", "mcp:exa"],   # search, read any URL, transcribe, GitHub/HN/arXiv, MCP
+    system_prompt="Cite every fact with a URL you opened.",
+)
+print(agent.run("Summarize https://youtu.be/<id> and find related papers").output)
+```
+
+```bash
+prompture doctor                               # what works on this machine and how to fix the rest
+prompture research "What changed in Python 3.13?" --depth quick   # cited multi-source report
+prompture transcribe talk.mp3 --summary        # timestamped transcript + key points
+prompture mcp add --preset exa                 # mount MCP servers by name
+prompture skill install                        # teach your coding agent all of this
+```
+
+- **Web:** keyless search, fetch and readers for YouTube, GitHub, Hacker News, arXiv, Wikipedia, feeds and podcasts
+- **Fails over instead of failing:** search, fetch and the readers try the next backend on auth, quota or rate-limit errors and tell you which one served the result
+- **Cached locally:** repeat searches and static pages come back instantly; weather, prices and news expire in minutes, papers and transcripts in days
+- **Safe by default:** public URLs only, size caps, secret scrubbing, and audio never goes to a second provider without your consent
+
+Full guide: [Capabilities](#capabilities).
+
 ## Prompture Desk: Usage in Your Tray
 
 **See what your LLM calls cost, live, from your tray.** [Prompture Desk](https://github.com/jhd3197/Prompture-Desk) tracks tokens and spend per provider and project, rate-limit headroom, balances, and your coding tools (Claude Code, Codex, …). Windows, macOS and Linux.
@@ -77,8 +110,7 @@ No setup: Desk runs `prompture companion` (Prompture 1.13+) on localhost for you
 **Agents, tools, RAG**
 - Stateful conversations with sync + async support
 - Function calling and streaming across providers, with prompt-based simulation for models without native tool use
-- Drop-in tools: sandboxed `python_execute` (Tukuy), keyless `web_search` / `web_fetch` / `read_url` (YouTube, GitHub, HN, arXiv, Wikipedia, feeds, podcasts) — see [Capabilities](#capabilities)
-- Mount tools by name: `tools=["web:all", "mcp:exa", "pack:finance", "cli:gh"]`; `ResearchAgent` for cited multi-source research
+- Drop-in tools: sandboxed `python_execute` (Tukuy) plus the [capability layer](#capabilities) below
 - `DeepAgent` with planning, virtual filesystem, sub-agents, and auto-summarization — no LangChain
 - Full RAG stack — loaders, chunkers, vector stores, hybrid dense+BM25 retrieval, end-to-end `RAGPipeline` — see [RAG](#rag)
 
@@ -87,8 +119,16 @@ No setup: Desk runs `prompture companion` (Prompture 1.13+) on localhost for you
 - `RefusalDetector` / `RefusalEvaluator` for cross-provider alignment scoring
 - `generate_qa_dataset()` — synthetic JSONL datasets ready for Unsloth, Axolotl, TRL
 
-**Ops**
+**Capabilities** — see [Capabilities](#capabilities)
+- Keyless `web_search`, `web_fetch` and `read_url` (YouTube, GitHub, HN, arXiv, Wikipedia, feeds, podcasts), with failover across keyed providers
+- Local web cache with content-aware lifetimes: minutes for weather, prices and news, days for papers and transcripts
+- `transcribe` / `summarize_media` for video, podcasts and audio, with timestamped key points
+- `ResearchAgent` / `prompture research` — cited multi-source reports within fetch, token, cost and time budgets
+- MCP hub, wrapped CLI tools (`gh`, `yt-dlp`) and domain packs (finance, news, dev, places), mounted by name: `tools=["mcp:exa", "pack:finance", "cli:gh"]`
 - `prompture doctor` — what works on this machine (providers, tools, media, MCP servers, binaries), which backend is active, and the exact fix for anything that isn't
+- `prompture setup` with an owner-only credential store and profiles; `prompture skill install` teaches coding agents to use all of it
+
+**Ops**
 - Resilient routing — `resilient()` retries transient errors, honors `Retry-After`, rotates API keys, trips circuit breakers and fails over across models; every response records who served it — see [Resilient Routing](#resilient-routing)
 - [Prompture Desk](#prompture-desk-usage-in-your-tray) — desktop tray app: usage per provider and project, rate limits and balances, live calls
 - [prompture-hub](#prompture-hub-gateway--dashboard) — optional companion app: web dashboard, scoped per-app keys, spend caps and per-call metering (`pip install prompture[hub]`)
@@ -1986,6 +2026,27 @@ agent = Agent("openai/gpt-4o", tools=["web:all"])
   refused, redirects are re-checked per hop, bodies are size-capped and
   challenge pages move to the next backend.
 
+**Local cache.** Results are cached in `~/.prompture/cache/web_cache.db`, so a
+repeated search or page comes back instantly, even from another process. Each
+entry lives as long as that kind of content stays true:
+
+| Content | Lifetime |
+|---|---|
+| Searches about weather, prices, scores, news, "today", or `recency_days <= 1` | 10 min |
+| Fast-moving pages (Hacker News, Reddit, X, status pages), GitHub issues/PRs | 10 min |
+| Feeds | 15 min |
+| Platform search (GitHub, HN, arXiv, YouTube) | 30 min |
+| Ordinary pages / searches within `recency_days <= 7` | 1 h |
+| Other searches | 6 h |
+| Wikipedia, podcast episodes | 1 day |
+| Papers, PDFs, DOIs, commit-pinned GitHub files, YouTube transcripts | 7 days |
+
+Cached results say so (`route["cached"]`, `cache_age_s`, and "cached 3 min
+ago" in the Markdown footer). Errors and empty results are never stored. Pass
+`use_cache=False` or `cache_ttl=<seconds>` per call, set
+`PROMPTURE_WEB_CACHE=memory|off` to change the store, and
+`clear_web_cache()` or `prompture reset` to empty it.
+
 ### Media understanding: transcripts and summaries
 
 ```python

{prompture-1.13.5.dev1 → prompture-1.13.5.dev3}/llms.txt

@@ -39,7 +39,7 @@ Model strings are `provider/model` (e.g. `openai/gpt-4o-mini`, `claude/claude-ha
 - `prompture.drivers`: one driver per provider; `get_driver_for_model("provider/model")`
 - `prompture.resilience`: `resilient()`, `classify_error`, combos and virtual models
 - `prompture.capabilities`: `BackendChain`, `probe_command`, `HealthStatus`, `safe_get`, `normalize_public_http_url`
-- `prompture.tools.web`: `web_search`, `web_fetch`, `read_url`, `search_platform`, `WebToolkit`
+- `prompture.tools.web`: `web_search`, `web_fetch`, `read_url`, `search_platform`, `WebToolkit`, local cache (`clear_web_cache`, `cache_info`, `PROMPTURE_WEB_CACHE`)
 - `prompture.media.understand`: `transcribe`, `summarize_media`
 - `prompture.mcp`: MCP client/server and `hub` (`MCPHub`, `resolve_mcp_tools`)
 - `prompture.tools.cli`, `prompture.tools.packs`: `CLITool`, domain packs

{prompture-1.13.5.dev1 → prompture-1.13.5.dev3}/prompture/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.13.5.dev1'
-__version_tuple__ = version_tuple = (1, 13, 5, 'dev1')
+__version__ = version = '1.13.5.dev3'
+__version_tuple__ = version_tuple = (1, 13, 5, 'dev3')
 
 __commit_id__ = commit_id = None

{prompture-1.13.5.dev1 → prompture-1.13.5.dev3}/prompture/capabilities/http.py

@@ -5,19 +5,31 @@
 ``max_bytes``, detects challenge interstitials, and raises typed errors that
 ``classify_error`` understands. Proxies come from ``PROMPTURE_<BACKEND>_PROXY``
 or ``PROMPTURE_PROXY``.
+
+Validating a hostname and then connecting to it resolves DNS twice, and a
+hostile DNS server can answer with a public address the first time and a
+private one the second (DNS rebinding). :class:`GuardedHTTPAdapter` closes that
+gap: it checks the address the socket *actually connected to*, before any
+request bytes are sent. Connections to a configured proxy are exempt, since
+the peer is then the proxy itself.
 """
 
 from __future__ import annotations
 
+import threading
+from contextvars import ContextVar
 from dataclasses import dataclass, field
 from typing import Any
 from urllib.parse import urljoin
 
 import requests
+from requests.adapters import HTTPAdapter
+from urllib3.connection import HTTPConnection, HTTPSConnection
+from urllib3.connectionpool import HTTPConnectionPool, HTTPSConnectionPool
 
 from .challenge import is_challenge_page
 from .errors import ChallengePageError, HTTPStatusError, ResponseTooLargeError, UnsafeURLError
-from .url_safety import normalize_public_http_url
+from .url_safety import allow_private_default, is_public_ip, normalize_public_http_url
 
 BROWSER_USER_AGENT = (
     "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
@@ -54,6 +66,92 @@ def proxies_for(backend: str | None = None) -> dict[str, str] | None:
     return {"http": proxy, "https": proxy} if proxy else None
 
 
+# ---------------------------------------------------------------------------
+# Connect-time address check (DNS rebinding)
+# ---------------------------------------------------------------------------
+
+# Per-request override of PROMPTURE_WEB_ALLOW_PRIVATE, set by safe_get.
+_allow_private: ContextVar[bool | None] = ContextVar("prompture_allow_private", default=None)
+
+
+def _check_peer(conn: Any, sock: Any) -> None:
+    """Refuse a socket that ended up connected to a non-public address."""
+    if getattr(conn, "proxy", None) is not None or getattr(conn, "_tunnel_host", None):
+        return  # the peer is the configured proxy, not the target
+    allow = _allow_private.get()
+    if allow is None:
+        allow = allow_private_default()
+    if allow:
+        return
+    try:
+        peer = sock.getpeername()[0]
+    except (OSError, IndexError):
+        return  # not an inet socket; nothing to check
+    if not is_public_ip(peer):
+        sock.close()
+        raise UnsafeURLError(f"{getattr(conn, 'host', 'host')} connected to non-public address {peer}")
+
+
+class _GuardedHTTPConnection(HTTPConnection):
+    def _new_conn(self) -> Any:
+        sock = super()._new_conn()
+        _check_peer(self, sock)
+        return sock
+
+
+class _GuardedHTTPSConnection(HTTPSConnection):
+    def _new_conn(self) -> Any:
+        sock = super()._new_conn()
+        _check_peer(self, sock)
+        return sock
+
+
+class _GuardedHTTPConnectionPool(HTTPConnectionPool):
+    ConnectionCls = _GuardedHTTPConnection
+
+
+class _GuardedHTTPSConnectionPool(HTTPSConnectionPool):
+    ConnectionCls = _GuardedHTTPSConnection  # type: ignore[assignment]
+
+
+class GuardedHTTPAdapter(HTTPAdapter):
+    """``requests`` adapter that refuses connections to non-public addresses.
+
+    The check runs on the connected socket, so it holds even when DNS answers
+    differently between validation and connection.
+    """
+
+    def init_poolmanager(self, *args: Any, **kwargs: Any) -> None:
+        super().init_poolmanager(*args, **kwargs)
+        self.poolmanager.pool_classes_by_scheme = {  # type: ignore[attr-defined]
+            "http": _GuardedHTTPConnectionPool,
+            "https": _GuardedHTTPSConnectionPool,
+        }
+
+
+def guard_session(session: requests.Session) -> requests.Session:
+    """Mount :class:`GuardedHTTPAdapter` on *session* (keeping its retry policy); returns it."""
+    for prefix in ("http://", "https://"):
+        current = session.get_adapter(prefix)
+        if not isinstance(current, GuardedHTTPAdapter):
+            retries = getattr(current, "max_retries", 0)
+            session.mount(prefix, GuardedHTTPAdapter(max_retries=retries))
+    return session
+
+
+_shared: requests.Session | None = None
+_shared_lock = threading.Lock()
+
+
+def guarded_session() -> requests.Session:
+    """Process-wide guarded session used when :func:`safe_get` gets none."""
+    global _shared
+    with _shared_lock:
+        if _shared is None:
+            _shared = guard_session(requests.Session())
+        return _shared
+
+
 @dataclass
 class SafeResponse:
     """Body and metadata of a completed :func:`safe_get`."""
@@ -122,10 +220,56 @@ def safe_get(
         backend: Backend name used to pick a per-backend proxy.
         raise_for_status: Raise :class:`HTTPStatusError` on non-2xx.
     """
-    http = session or requests.Session()
+    if allow_private is None:
+        allow_private = allow_private_default()
+    if isinstance(session, requests.Session):
+        http: Any = guard_session(session)
+    elif session is not None:
+        http = session  # a duck-typed client (tests); URL checks still apply
+    elif allow_private:
+        # Keep private-network connections out of the shared pool.
+        http = guard_session(requests.Session())
+    else:
+        http = guarded_session()
     merged = {**DEFAULT_HEADERS, **(headers or {})}
     proxies = proxies_for(backend)
     current = normalize_public_http_url(url, allow_private=allow_private)
+    token = _allow_private.set(allow_private)
+    try:
+        return _get_with_redirects(
+            http,
+            current,
+            headers=merged,
+            params=params,
+            timeout=timeout,
+            proxies=proxies,
+            max_bytes=max_bytes,
+            max_redirects=max_redirects,
+            allow_private=allow_private,
+            check_challenge=check_challenge,
+            truncate=truncate,
+            raise_for_status=raise_for_status,
+        )
+    finally:
+        _allow_private.reset(token)
+
+
+def _get_with_redirects(
+    http: Any,
+    current: str,
+    *,
+    headers: dict[str, str],
+    params: dict[str, Any] | None,
+    timeout: float,
+    proxies: dict[str, str] | None,
+    max_bytes: int,
+    max_redirects: int,
+    allow_private: bool,
+    check_challenge: bool,
+    truncate: bool,
+    raise_for_status: bool,
+) -> SafeResponse:
+    merged = headers
     history: list[str] = []
     query = params
 

{prompture-1.13.5.dev1 → prompture-1.13.5.dev3}/prompture/cli/setup_cmd.py

@@ -550,7 +550,7 @@ _STATE_DESCRIPTIONS = {
     "credentials.yaml": "stored credentials and settings",
     "mcp.json": "named MCP servers",
     "usage": "usage ledger databases",
-    "cache": "model-rate, response and plan-usage caches",
+    "cache": "model-rate, response, web and plan-usage caches",
     "update_check.json": "update-check state",
     "companion.json": "local companion address and token",
     "companion-prefs.json": "companion preferences",

{prompture-1.13.5.dev1 → prompture-1.13.5.dev3}/prompture/infra/logging.py

@@ -21,6 +21,7 @@ Usage::
 
 from __future__ import annotations
 
+import contextlib
 import json
 import logging
 from datetime import datetime, timezone
@@ -43,6 +44,16 @@ class SecretScrubbingFilter(logging.Filter):
         if scrubbed != message:
             record.msg = scrubbed
             record.args = None
+        # Formatters append the traceback after the message, and exception
+        # text often carries the very URL or key we just scrubbed. Render it
+        # now and store the scrubbed copy; formatters reuse ``exc_text``.
+        if record.exc_info and not record.exc_text:
+            with contextlib.suppress(Exception):
+                record.exc_text = logging.Formatter().formatException(record.exc_info)
+        if record.exc_text:
+            record.exc_text = scrub_secrets(record.exc_text)
+        if record.stack_info:
+            record.stack_info = scrub_secrets(record.stack_info)
         return True
 
 

{prompture-1.13.5.dev1 → prompture-1.13.5.dev3}/prompture/research/agent.py

@@ -86,8 +86,11 @@ def default_research_model() -> str | None:
     cheap model of the first configured provider in
     :data:`DEFAULT_MODEL_CANDIDATES`. ``None`` when nothing is configured.
     """
+    from ..infra.credentials import get_config_value
+
     for var in ("PROMPTURE_RESEARCH_MODEL", "PROMPTURE_DEFAULT_MODEL"):
-        value = os.environ.get(var, "").strip()
+        # Env first, then the credential store, where `prompture setup` saves the default model.
+        value = (get_config_value(var) or "").strip()
         if value:
             return value
     try:
@@ -364,6 +367,10 @@ class _ResearchRun:
         self.fetched: dict[str, _Fetched] = {}
         self._lock = threading.Lock()
         self._emit_lock = threading.Lock()
+        # Packs run in parallel, but under a token/cost budget their LLM calls
+        # take turns: checking the budget and recording usage happen under this
+        # lock, so concurrent calls can't all pass the check and overshoot.
+        self._llm_budget_lock = threading.Lock()
         self.search_ok = 0
         self.search_failed = 0
 
@@ -494,18 +501,21 @@ class _ResearchRun:
         )
 
     def _pack_one(self, pack: str) -> None:
-        if not self.tracker.llm_budget_left():
-            return
-        try:
-            text, usage = _call_with_deadline(
-                lambda: self.agent._run_pack(pack, self.question), self.tracker.gather_remaining()
-            )
-        except Exception as exc:
-            with self._lock:
-                self.routes.append({"op": "pack", "target": pack, "ok": False, "error": _short_error(exc)})
-            self.emit("search", f"Pack {pack} unavailable", pack=pack, ok=False)
-            return
-        self.tracker.record_usage(usage)
+        budgeted = self.tracker.budget.max_tokens is not None or self.tracker.budget.max_cost is not None
+        guard = self._llm_budget_lock if budgeted else contextlib.nullcontext()
+        with guard:
+            if not self.tracker.llm_budget_left():
+                return
+            try:
+                text, usage = _call_with_deadline(
+                    lambda: self.agent._run_pack(pack, self.question), self.tracker.gather_remaining()
+                )
+            except Exception as exc:
+                with self._lock:
+                    self.routes.append({"op": "pack", "target": pack, "ok": False, "error": _short_error(exc)})
+                self.emit("search", f"Pack {pack} unavailable", pack=pack, ok=False)
+                return
+            self.tracker.record_usage(usage)
         text = (text or "").strip()
         with self._lock:
             self.routes.append({"op": "pack", "target": pack, "ok": bool(text), "served_by": f"pack:{pack}"})

{prompture-1.13.5.dev1 → prompture-1.13.5.dev3}/prompture/skill/data/SKILL.md

@@ -7,9 +7,12 @@ description: Use when you need to search the web, read a URL (pages, PDFs, YouTu
 
 Prompture gives agents working capabilities — search, read, watch, listen,
 call models and external tools — and tells you exactly what works on this
-machine and how to fix what doesn't. Everything has a keyless default; keys
-only raise limits or quality. Every capability fails over to the next backend
-instead of failing, and says which backend served it.
+machine and how to fix what doesn't. Web search and URL reading have keyless
+defaults; keys only raise their limits or quality. Model calls, transcription,
+packs and MCP servers need the provider, key, package or binary that doctor
+names. Where a capability has more than one permitted backend, it fails over
+and reports which one served the request and whether a fallback happened.
+Transcription never moves audio to a second provider without explicit consent.
 
 Install: `pip install prompture` (extras: `prompture[web]`, `prompture[media]`,
 `prompture[mcp]`, `prompture[all]`).

{prompture-1.13.5.dev1 → prompture-1.13.5.dev3}/prompture/skill/data/references/search.md

@@ -65,6 +65,14 @@ The report only cites pages it actually opened. Model defaults to
 `PROMPTURE_RESEARCH_MODEL`, then the first configured provider's cheap model.
 Other agents can call it as a tool: `tools=[research_tool(depth="quick")]`.
 
+## Cache
+
+Results are cached locally (`~/.prompture/cache/web_cache.db`). Volatile
+searches (weather, prices, scores, news, "today", `recency_days <= 1`) live 10
+minutes; others live hours. A cached result has `route["cached"] is True` and
+`route["cache_age_s"]` — say so when it matters ("from a search 5 min ago").
+For something that must be live right now, pass `use_cache=False`.
+
 ## When search fails
 
 1. `prompture doctor --only tools --json` → look at the `web_search` row.

{prompture-1.13.5.dev1 → prompture-1.13.5.dev3}/prompture/skill/data/references/web.md

@@ -41,8 +41,18 @@ if page.truncated:
     more = web_fetch(page.url, start=page.next_start)   # paging
 ```
 
-Long pages end with `[truncated — call again with start=N]`. Results are
-cached for 10 minutes. `compress=True` trims boilerplate for agent loops.
+Long pages end with `[truncated — call again with start=N]`; paging reads
+from the cache, not the network. `compress=True` trims boilerplate for agent
+loops.
+
+## Cache
+
+`web_fetch`, `read_url` and `search_platform` share a local cache whose
+lifetime follows the content: 10 minutes for Hacker News, Reddit, X, status
+pages and GitHub issues/PRs, 1 hour for ordinary pages, 1 day for Wikipedia,
+7 days for papers, PDFs, DOIs and YouTube transcripts. Cached results carry
+`route["cached"]` and `route["cache_age_s"]`. Use `use_cache=False` when the
+user needs the page as it is right now; `PROMPTURE_WEB_CACHE=off` disables it.
 
 ## Safety (don't work around these)
 

{prompture-1.13.5.dev1 → prompture-1.13.5.dev3}/prompture/tools/cli/adapter.py

@@ -580,6 +580,10 @@ class CLITool:
             secrets never have to live in a config file. Values are never logged.
         install_hint: Fix hint when the binary is missing.
         prefix: Tool-name prefix (defaults to *name* with ``-`` → ``_``).
+        trusted: Whether health checks may execute the binary. Tools from a
+            project's ``.prompture/tools.*`` are untrusted: a repository could
+            point ``command`` / ``version_args`` at arbitrary code, so doctor
+            and ``cli:all`` only locate their executable and never run it.
     """
 
     name: str
@@ -593,6 +597,7 @@ class CLITool:
     env: dict[str, str] = field(default_factory=dict)
     install_hint: str | None = None
     prefix: str | None = None
+    trusted: bool = True
 
     def __post_init__(self) -> None:
         if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,40}", self.name or ""):
@@ -730,10 +735,16 @@ class CLITool:
         return _ON_WINDOWS and path.lower().endswith((".bat", ".cmd"))
 
     def is_active(self) -> bool:
-        """True when the binary exists and its version probe succeeds."""
+        """True when the binary exists and (for trusted tools) its version probe succeeds.
+
+        Untrusted, project-defined tools are never executed here; finding the
+        executable is enough.
+        """
         path = self._resolve()
         if path is None or self._is_batch_launcher(path):
             return False
+        if not self.trusted:
+            return True
         return cached_probe(self.command, self.version_args, hint=self.install_hint).ok
 
     def check(self, live: bool = False) -> HealthStatus:
@@ -750,6 +761,8 @@ class CLITool:
                 fix_hint=f"Point `command` at the real executable for {self.name}.",
                 details={**details, "path": path},
             )
+        if not self.trusted:
+            return self._untrusted_check(row_name, path, details)
         probe = cached_probe(self.command, self.version_args, hint=self.install_hint or install_hint(self.command))
         details.update(path=probe.path, version=probe.version if probe.ok else None, exit_code=probe.exit_code)
         if not probe.ok:
@@ -789,6 +802,35 @@ class CLITool:
             details=details,
         )  # type: ignore[arg-type]
 
+    def _untrusted_check(self, row_name: str, path: str | None, details: dict[str, Any]) -> HealthStatus:
+        """Health row for a project-defined tool: locate the executable, never run it."""
+        details.update(path=path, trusted=False)
+        if path is None:
+            return HealthStatus(
+                row_name,
+                "missing",
+                category="tools",
+                message=f"`{self.command}` not found on PATH",
+                fix_hint=self.install_hint or install_hint(self.command),
+                details=details,
+            )
+        _, missing = self._injected_env()
+        fix = None
+        status = "ok"
+        if missing:
+            status = "degraded"
+            fix = "Set " + ", ".join(sorted(set(missing))) + f" (referenced by {self.name} env)."
+            details["missing_env"] = sorted(set(missing))
+        return HealthStatus(
+            row_name,
+            status,  # type: ignore[arg-type]
+            category="tools",
+            active_backend=path,
+            message=f"found at {path}; project-defined, so not executed by health checks",
+            fix_hint=fix,
+            details=details,
+        )
+
     # -- execution ------------------------------------------------------
 
     def run(self, command: str, **params: Any) -> CLIResult: