Autonomous AI sales agent powered by Claude Code or Codex. Finds prospects, writes cold emails, sends campaigns, handles replies, books meetings. No API keys needed — runs on your Claude or Codex subscriptions.
Share one configurable Hunter budget across all domain-searches
Ethan55908b067bee
diff --git a/.env.example b/.env.exampleindex 3c5b462..8642a25 100644--- a/.env.example+++ b/.env.example@@ -80,6 +80,9 @@ ZEROBOUNCE_API_KEY=# Harvey verifies one address instead of guessing six).# Where to get it: https://hunter.io → sign up → API → API KeysHUNTER_API_KEY=+# Domain-searches per month across all of Harvey. 25 matches Hunter's free+# tier; set this to your plan's allowance if you pay for Hunter.+HUNTER_MONTHLY_SEARCHES=25# ------------------------------------------------------------# DISCOVERY — where Harvey finds businesses. [ALL OPTIONAL]diff --git a/harvey/agents/scout.py b/harvey/agents/scout.pyindex 3ca6e39..e0fe194 100644--- a/harvey/agents/scout.py+++ b/harvey/agents/scout.py@@ -59,12 +59,10 @@ MAX_RESULTS_PER_QUERY = 20MAX_COMPANIES_PER_CYCLE = 10MAX_PROSPECTS_PER_CYCLE = 25-# Hunter's free tier is 25 domain-searches/month total, and each call costs-# a credit regardless of how many people it returns — a heartbeat running-# every 15 minutes would blow through that in under an hour uncapped, so-# usage is tracked explicitly (see _prospect_via_hunter) rather than trusted-# to fail gracefully once exhausted.-HUNTER_MONTHLY_CAP = 25+# Hunter domain-searches per heartbeat. The monthly budget itself is shared+# with email-pattern lookups and set by HUNTER_MONTHLY_SEARCHES (see+# integrations/email_finder.py); this just paces it, since a heartbeat every+# 15 minutes would spend a free-tier month in a few hours otherwise.HUNTER_DOMAINS_PER_CYCLE = 1# Rotate a small pool of realistic desktop user-agents. Scrapers that always@@ -134,8 +132,8 @@ class Scout:strategies = []# Hunter first, if configured: real named people with a real# verification verdict beats a scrape guess, but the free tier's- # 25/month cap means it only ever covers a handful of companies —- # self-skips once the monthly quota (tracked in settings) is spent.+ # monthly budget (HUNTER_MONTHLY_SEARCHES, 25 by default) is small —+ # self-skips once it's spent.strategies.append(("hunter", self._prospect_via_hunter))# Backfill next: companies already on file (e.g. from `harvey# discover`) but with zero prospects. Scrapes each company's own@@ -484,21 +482,18 @@ class Scout:"""Pull Hunter's actual named-people data for companies with zeroprospects — real name/title/email/verification, not a scrape guess.- Hunter's free tier is 25 domain-searches/month for the whole- account, so this draws from the same rotating pool as the team-page- backfill but at a much smaller, explicitly quota-tracked pace.+ Draws from the same rotating pool as the team-page backfill, but at+ a much smaller pace and against the shared monthly Hunter budget."""api_key = getattr(self.env, "hunter_api_key", "") or ""if not api_key:return 0- month_key = datetime.now(timezone.utc).strftime("%Y-%m")- setting_key = f"hunter_domain_search_count:{month_key}"- try:- used = int(await self.state.get_setting(setting_key, "0") or "0")- except ValueError:- used = 0- remaining = HUNTER_MONTHLY_CAP - used+ from harvey.integrations.email_finder import (+ hunter_domain_people, hunter_searches_remaining, record_hunter_search,+ )++ remaining = await hunter_searches_remaining(self.state)if remaining <= 0:return 0@@ -511,8 +506,6 @@ class Scout:if not companies:return 0- from harvey.integrations.email_finder import hunter_domain_people-default_industry = (self.config.icp.industries[0] if self.config.icp.industries else "")@@ -522,12 +515,10 @@ class Scout:if not domain:continue+ if await hunter_searches_remaining(self.state) <= 0:+ break+ await record_hunter_search(self.state)people = await hunter_domain_people(domain, api_key)- used += 1- try:- await self.state.set_setting(setting_key, str(used))- except Exception as e:- logger.debug(f"set_setting failed for {setting_key}: {e}")try:await self.state.mark_prospects_checked(company["id"])except Exception as e:@@ -575,9 +566,6 @@ class Scout:if count >= MAX_PROSPECTS_PER_CYCLE:return count- if used >= HUNTER_MONTHLY_CAP:- break-return count# ── Strategy 0: Known companies with zero prospects ──diff --git a/harvey/integrations/email_finder.py b/harvey/integrations/email_finder.pyindex 173882c..733ecd7 100644--- a/harvey/integrations/email_finder.py+++ b/harvey/integrations/email_finder.py@@ -25,6 +25,7 @@ import osimport randomimport refrom dataclasses import dataclass+from datetime import datetime, timezonefrom typing import Optionalimport dns.resolver@@ -230,6 +231,55 @@ def _hunter_api_key() -> str:return os.getenv("HUNTER_API_KEY", "").strip()+# Hunter's free tier is 25 domain-searches/month for the whole account, and+# every call spends one no matter how many people it returns. Paid plans set+# HUNTER_MONTHLY_SEARCHES to their own allowance. Every domain-search call in+# Harvey draws from this one counter, so the pattern lookup and Scout's+# named-contact strategy can't each assume they have the full quota.+HUNTER_FREE_MONTHLY_SEARCHES = 25+++def _hunter_monthly_cap() -> int:+ raw = os.getenv("HUNTER_MONTHLY_SEARCHES", "").strip()+ if not raw:+ return HUNTER_FREE_MONTHLY_SEARCHES+ try:+ return max(int(raw), 0)+ except ValueError:+ return HUNTER_FREE_MONTHLY_SEARCHES+++def _hunter_usage_key() -> str:+ return f"hunter_domain_search_count:{datetime.now(timezone.utc):%Y-%m}"+++async def hunter_searches_remaining(state) -> int:+ """Domain-searches left this calendar month (UTC). Without a state+ store there is nothing to count against, so the full cap is reported."""+ cap = _hunter_monthly_cap()+ if state is None:+ return cap+ try:+ used = int(await state.get_setting(_hunter_usage_key(), "0") or "0")+ except (ValueError, TypeError):+ used = 0+ except Exception as e:+ logger.debug(f"Hunter usage read failed: {e}")+ return 0+ return max(cap - used, 0)+++async def record_hunter_search(state) -> None:+ """Count one domain-search against this month's budget. Called before+ the request, so a call that fails mid-flight is still counted."""+ if state is None:+ return+ try:+ await state.increment_setting(_hunter_usage_key())+ except Exception as e:+ logger.debug(f"Hunter usage write failed: {e}")++async def hunter_domain_people(domain: str, api_key: str, limit: int = 10) -> Optional[list[dict]]:@@ -238,9 +288,9 @@ async def hunter_domain_people(and its own verification verdict). Returns the raw ``emails`` list, orNone on any failure (network, non-200, bad JSON, or no data).- Costs one domain-search credit per call regardless of ``limit`` — the- free tier is 25/month, so callers must budget calls, not rely on this- failing gracefully to protect the quota.+ Costs one domain-search credit per call regardless of ``limit``, so+ callers must check hunter_searches_remaining() and record_hunter_search()+ first rather than rely on this failing gracefully to protect the quota."""try:async with httpx.AsyncClient(timeout=API_TIMEOUT) as client:@@ -290,7 +340,8 @@ async def derive_pattern(return inferred, "known_email", 0.9key = _hunter_api_key()- if key:+ if key and await hunter_searches_remaining(state) > 0:+ await record_hunter_search(state)result = await _hunter_domain_pattern(domain, key)if result:return result[0], "hunter_domain_search", result[1]diff --git a/tests/test_email_finder.py b/tests/test_email_finder.pyindex e2236d3..ec68ca0 100644--- a/tests/test_email_finder.py+++ b/tests/test_email_finder.py@@ -219,3 +219,38 @@ async def test_find_email_inconclusive_is_guess_not_verified(state, monkeypatch)result = await find_email("Jane", "Doe", "acme.com", env=Env(), state=state)assert result.status == "guess"assert not result.verified+++# ── shared Hunter domain-search budget ──+++async def test_hunter_budget_defaults_to_free_tier(state, monkeypatch):+ monkeypatch.delenv("HUNTER_MONTHLY_SEARCHES", raising=False)+ assert await ef.hunter_searches_remaining(state) == 25+ await ef.record_hunter_search(state)+ assert await ef.hunter_searches_remaining(state) == 24+++async def test_hunter_budget_follows_paid_plan_setting(state, monkeypatch):+ monkeypatch.setenv("HUNTER_MONTHLY_SEARCHES", "500")+ assert await ef.hunter_searches_remaining(state) == 500+++async def test_derive_pattern_spends_and_respects_hunter_budget(state, monkeypatch):+ monkeypatch.setattr(ef, "_hunter_api_key", lambda: "k")+ monkeypatch.setenv("HUNTER_MONTHLY_SEARCHES", "1")+ calls = []++ async def fake_hunter(domain, key):+ calls.append(domain)+ return "{f}.{l}", 0.8++ monkeypatch.setattr(ef, "_hunter_domain_pattern", fake_hunter)+ _, source, _ = await derive_pattern("first-co.com", state=state)+ assert source == "hunter_domain_search"+ _, source, _ = await derive_pattern("second-co.com", state=state)+ assert source == "default"+ assert calls == ["first-co.com"]