Skip to content

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.

Address review: per-draft Humanizer calls, strict inbox allowlist

Ethanb49b648eebb4
diff --git a/README.md b/README.md
index dfbb969..26099a9 100644
--- a/README.md
+++ b/README.md
@@ -226,7 +226,7 @@ Agency detection is the compounding one. Almost every agency credits itself in t
Free public registries first. Name plus title from the team page, confirmed against an authoritative registry where one exists — which also filters out your own parsing artifacts, because a "person" who matches nothing usually wasn't one.
-When a company's site names nobody and Harvey has no contact there yet — common for small trades — it falls back to a general address the company prints on its own homepage or contact page (`owner@`, `office@`, `info@` preferred; `careers@`, `noreply@` and similar skipped). It is never guessed, it is verified like any other address, and those emails greet the company's team instead of a first name.
+When a company's site names nobody and Harvey has no contact there yet — common for small trades — it falls back to a general address the company prints on its own homepage or contact page (only general mailboxes such as `owner@`, `office@`, `info@` or `hello@`, never a person's own address). It is never guessed, it is verified like any other address, and those emails greet the company's team instead of a first name.
### 4. VERIFY — can you reach them
diff --git a/harvey/agents/scout.py b/harvey/agents/scout.py
index 7c94139..12f4ede 100644
--- a/harvey/agents/scout.py
+++ b/harvey/agents/scout.py
@@ -30,7 +30,7 @@ import logging
import random
import re
from datetime import datetime, timezone
-from urllib.parse import parse_qs, quote_plus, urlparse
+from urllib.parse import parse_qs, quote_plus, unquote, urlparse
import httpx
from bs4 import BeautifulSoup
@@ -58,17 +58,15 @@ BACKOFF_BASE = 1.5 # seconds; grows exponentially per attempt
MAX_RESULTS_PER_QUERY = 20
MAX_COMPANIES_PER_CYCLE = 10
-# Company-inbox fallback: pages that publish a general address, the
-# mailboxes most likely read by the owner (best first), and addresses that
-# never reach a decision-maker.
+# Company-inbox fallback: pages that publish a general address, and the
+# only mailboxes it will use, most likely read by the owner first. An
+# allowlist, not a blocklist: a personal address (jane.doe@) on a contact
+# page is a person Harvey chose not to target, never "the team".
INBOX_PAGES = ("/contact", "/contact-us")
-INBOX_PREFERRED = ("owner", "office", "info", "contact", "service", "hello",
- "sales", "admin", "support")
-INBOX_SKIP_LOCALS = {
- "noreply", "no-reply", "donotreply", "careers", "jobs", "hr", "billing",
- "accounting", "invoices", "ap", "press", "media", "marketing", "privacy",
- "webmaster", "abuse", "postmaster", "example", "email", "name", "your",
-}
+INBOX_PREFERRED = ("owner", "office", "info", "contact", "contactus", "hello",
+ "team", "service", "sales", "estimates", "quotes",
+ "inquiries", "enquiries", "admin", "support")
+INBOX_ADDRESS = re.compile(r"[a-z0-9._+\-]+@[a-z0-9.\-]+\.[a-z]{2,}")
MAX_PROSPECTS_PER_CYCLE = 25
# Hunter domain-searches per heartbeat. The monthly budget itself is shared
@@ -1461,10 +1459,10 @@ Respond ONLY with the JSON array."""
self._remember_prospect(prospect)
contacts.append(prospect)
- # The inbox is a last resort for a company nobody at Harvey has a
- # contact for. A named person found here (even one skipped as a
- # duplicate on a revisit) or already on file from another source
- # means the company is covered: never email it a second time.
+ # The inbox is a last resort for a company Harvey has no contact at.
+ # A named person found here (even one skipped as a duplicate on a
+ # revisit) or already on file from another source means the
+ # company is covered, so its inbox isn't added on top.
if not contacts and not named_on_site and await self._company_uncontacted(company_id):
inbox = await self._company_inbox_prospect(
company_id, domain, company_name, industry, signal_note,
@@ -1540,25 +1538,23 @@ Respond ONLY with the JSON array."""
for a in soup.find_all("a", href=True):
href = self._attr_str(a.get("href"))
if href.lower().startswith("mailto:"):
- found.append(href[7:].split("?")[0])
- found += re.findall(r"[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}", text[:50000])
+ found.append(unquote(href[7:].split("?")[0]))
+ found.append(unquote(text[:50000]))
+ # Pull clean addresses out of everything found ("%[email protected]",
+ # a trailing full stop), then keep only general on-domain inboxes.
candidates = []
- for addr in found:
- addr = addr.strip().lower()
- local, _, adomain = addr.partition("@")
- if adomain.removeprefix("www.") != domain or local in INBOX_SKIP_LOCALS:
- continue
- if addr not in candidates:
- candidates.append(addr)
+ for chunk in found:
+ for addr in INBOX_ADDRESS.findall(chunk.lower()):
+ addr = addr.rstrip(".")
+ local, _, adomain = addr.partition("@")
+ if adomain.removeprefix("www.") != domain or local not in INBOX_PREFERRED:
+ continue
+ if addr not in candidates:
+ candidates.append(addr)
if not candidates:
return ""
-
- def rank(addr: str) -> int:
- local = addr.partition("@")[0]
- return INBOX_PREFERRED.index(local) if local in INBOX_PREFERRED else len(INBOX_PREFERRED)
-
- return min(candidates, key=rank)
+ return min(candidates, key=lambda a: INBOX_PREFERRED.index(a.partition("@")[0]))
# ── Strategy 4: Job boards — companies hiring for signal roles ──
diff --git a/harvey/agents/writer.py b/harvey/agents/writer.py
index 564832c..b2b6591 100644
--- a/harvey/agents/writer.py
+++ b/harvey/agents/writer.py
@@ -11,6 +11,7 @@ design). Every draft still passes the deterministic pre-send gate.
import json
import logging
+import re
from datetime import datetime, timezone
from harvey.brain import Brain
@@ -22,6 +23,9 @@ from harvey.state import StateManager
logger = logging.getLogger("harvey.writer")
+# Merge variables that name a person; a company inbox has none of them.
+PERSON_VAR = re.compile(r"\{\{\s*(first_name|last_name|title)\s*\}\}")
+
# Native mode: one Claude call per prospect for email 1, so batches stay
# small — the rest of the 'new' pool is picked up on later cycles.
NATIVE_BATCH_CAP = 8
@@ -332,6 +336,13 @@ Return ONLY a JSON array (no markdown fences, no commentary):
agent="writer", task="write_sequence",
)
steps = self._parse_sequence(result)
+ if inbox_batch and any(
+ PERSON_VAR.search(s.subject + s.body) for s in steps
+ ):
+ # Nobody's name is known: "Hi {{first_name}}" or "as {{title}}"
+ # would render as "Hi there" at best and "as General inbox" at worst.
+ logger.warning("Writer: inbox sequence used a person merge variable; discarding it.")
+ return []
polished = await humanize(
self.brain, [{"subject": s.subject, "body": s.body} for s in steps],
agent="writer", enabled=humanizer_enabled(self.config),
diff --git a/harvey/humanize.py b/harvey/humanize.py
index 0b96510..92105b5 100644
--- a/harvey/humanize.py
+++ b/harvey/humanize.py
@@ -29,7 +29,7 @@ SKILL_PATH = Path(
)
)
MERGE_VAR = re.compile(r"\{\{\s*\w+\s*\}\}")
-MAX_GROWTH = 1.2 # a rewrite may not be more than 20% longer than the draft
+MAX_GROWTH_WORDS = 2 # a rewrite may not be more than two words longer
# A rewrite that talks about itself instead of being the email.
META_PREFIXES = ("i can't", "i cannot", "as an ai", "sorry,", "here is", "here's")
@@ -67,7 +67,8 @@ def _acceptable(original: dict, rewrite) -> bool:
return False
if "—" in after and "—" not in before:
return False
- return len(body.split()) <= len(original["body"].split()) * MAX_GROWTH + 2
+ # The writer's word caps were met by the draft; an edit must not undo that.
+ return len(body.split()) <= len(original["body"].split()) + MAX_GROWTH_WORDS
async def humanize(
@@ -76,10 +77,11 @@ async def humanize(
) -> list[dict]:
"""Return ``drafts`` ({"subject", "body"} dicts) rewritten by the skill.
- A no-op unless ``enabled`` (see ``humanizer_enabled``).
-
- One brain call for the whole list. Any draft whose rewrite fails a check
- comes back unchanged, so the result always has the same length and order.
+ A no-op unless ``enabled`` (see ``humanizer_enabled``). One brain call
+ per draft: personal drafts carry real names and companies, so a batched
+ call that came back reordered could hand one prospect another's email.
+ Any draft whose rewrite fails a check comes back unchanged, so the
+ result always has the same length and order.
"""
if not enabled or not drafts:
return drafts
@@ -87,49 +89,45 @@ async def humanize(
if not skill:
return drafts
- payload = [{"subject": d.get("subject", ""), "body": d["body"]} for d in drafts]
+ out = [await _humanize_one(brain, skill, draft, agent) for draft in drafts]
+ kept = sum(1 for a, b in zip(drafts, out) if a is b)
+ if kept:
+ logger.info(f"Humanizer: kept {kept} of {len(drafts)} draft(s) unchanged after checks.")
+ return out
+
+
+async def _humanize_one(brain, skill: str, draft: dict, agent: str) -> dict:
+ payload = {"subject": draft.get("subject", ""), "body": draft["body"]}
prompt = f"""{skill}
---
-Apply the Humanizer instructions above to the cold-email drafts below. They
-are short plain-text business emails, so return email text only.
+Apply the Humanizer instructions above to the cold-email draft below. It is
+a short plain-text business email, so return email text only.
Hard limits on the rewrite, on top of the instructions above:
-- Same number of items, same order.
- Keep every merge variable such as {{{{first_name}}}} or {{{{company}}}} exactly as written.
- Add no fact, name, number or claim that is not already in the draft.
- No em dashes, no bullets, no bold, no exclamation marks.
-- Do not make any email longer. Keep exactly one question per email.
-- Subjects stay lowercase, 2-5 words. An empty subject stays empty.
+- Do not make the email longer. Keep exactly one question.
+- The subject stays lowercase, 2-5 words. An empty subject stays empty.
-Drafts:
+Draft:
{json.dumps(payload, ensure_ascii=False, indent=2)}
-Return ONLY a JSON array: [{{"subject": "...", "body": "..."}}, ...]"""
+Return ONLY a JSON object: {{"subject": "...", "body": "..."}}"""
try:
- result = await brain.think_json(
+ rewrite = await brain.think_json(
prompt, session_id="harvey-humanizer", agent=agent, task="humanize",
)
except Exception as e:
- logger.warning(f"Humanizer pass failed, keeping drafts: {e}")
- return drafts
- if not isinstance(result, list) or len(result) != len(drafts):
- logger.warning("Humanizer pass returned the wrong shape, keeping drafts.")
- return drafts
-
- out = []
- for original, rewrite in zip(drafts, result):
- if _acceptable(original, rewrite):
- out.append({
- **original,
- "subject": str(rewrite.get("subject") or "").strip(),
- "body": str(rewrite["body"]).strip(),
- })
- else:
- out.append(original)
- kept = sum(1 for a, b in zip(drafts, out) if a is b)
- if kept:
- logger.info(f"Humanizer: kept {kept} of {len(drafts)} draft(s) unchanged after checks.")
- return out
+ logger.warning(f"Humanizer pass failed, keeping draft: {e}")
+ return draft
+ if not _acceptable(draft, rewrite):
+ return draft
+ return {
+ **draft,
+ "subject": str(rewrite.get("subject") or "").strip(),
+ "body": str(rewrite["body"]).strip(),
+ }
diff --git a/harvey/integrations/email_finder.py b/harvey/integrations/email_finder.py
index b36d936..f1cbc7e 100644
--- a/harvey/integrations/email_finder.py
+++ b/harvey/integrations/email_finder.py
@@ -379,7 +379,7 @@ async def verify_reoon(email: str, api_key: str) -> Optional[dict]:
return None
status = str(data.get("status") or "").lower()
if status == "role_account":
- status = "valid" if data.get("is_deliverable") else "unknown"
+ status = "valid" if data.get("is_deliverable") is True else "unknown"
is_catch_all = bool(data.get("is_catch_all") or status == "catch_all")
return {"status": status, "catch_all": is_catch_all}
diff --git a/tests/test_company_inbox.py b/tests/test_company_inbox.py
index 49af1e8..6ad265e 100644
--- a/tests/test_company_inbox.py
+++ b/tests/test_company_inbox.py
@@ -79,6 +79,33 @@ async def test_published_address_without_mail_server_is_invalid(monkeypatch):
assert await ef.verify_published_address("[email protected]") == "invalid"
[email protected]("deliverable, expected", [(True, "valid"), ("false", "unknown"), (None, "unknown")])
+async def test_reoon_role_account_needs_a_real_deliverable_flag(monkeypatch, deliverable, expected):
+ class Resp:
+ status_code = 200
+
+ def json(self):
+ return {"status": "role_account", "is_deliverable": deliverable}
+
+ class Client:
+ def __init__(self, **kw):
+ pass
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, *a):
+ return False
+
+ async def get(self, url, params=None):
+ return Resp()
+
+ monkeypatch.setattr(ef.httpx, "AsyncClient", Client)
+ verdict = await ef.verify_reoon("[email protected]", "key")
+ assert verdict["status"] == expected
+
+
# ── scout ──
PAGES = {
@@ -131,6 +158,24 @@ async def test_inbox_prospect_carries_its_verification(monkeypatch):
assert p.is_company_inbox and p.company_id == "c1"
+async def test_a_personal_address_is_not_a_company_inbox():
+ # Jane may have been skipped on purpose as non-ICP; she isn't "the team".
+ pages = {"https://acme.com": "Jane Doe, receptionist: [email protected]"}
+ assert await make_scout(pages)._find_inbox_address("acme.com") == ""
+
+
+ '<a href="mailto:%[email protected]">Email</a>',
+ '<a href="MAILTO:[email protected]?subject=Quote">Email</a>',
+ "Email us at [email protected].",
+ "Email us at %[email protected]",
+])
+async def test_published_address_is_cleaned(html):
+ assert await make_scout({"https://acme.com": html})._find_inbox_address("acme.com") == "[email protected]"
+
+
# ── fallback only when the company has nobody ──
def fallback_scout(team, existing=(), duplicate=False):
@@ -209,3 +254,46 @@ def test_inbox_prospects_get_their_own_campaign():
named = Prospect(first_name="Jo", last_name="Li", title="Owner", industry="Roofing", email="[email protected]")
batches = writer._group_prospects([named, inbox(industry="Roofing")])
assert set(batches) == {"Roofing-outreach", "Roofing-inbox-outreach"}
+
+
+class SequenceBrain:
+ def __init__(self, steps):
+ self.steps = steps
+
+ def load_prompt(self, name, **kw):
+ return "prompt"
+
+ async def think_json(self, prompt, **kw):
+ return self.steps
+
+
+def sequence_writer(steps):
+ from harvey.agents.writer import Writer
+ writer = Writer.__new__(Writer)
+ writer.brain = SequenceBrain(steps)
+ writer.skills = ""
+ writer.config = SimpleNamespace(
+ product=SimpleNamespace(name="P", description="D", key_benefits=[], pricing=""),
+ persona=SimpleNamespace(name="S", company="C", role="R", tone="t"),
+ )
+ return writer
+
+
[email protected]("var", ["{{first_name}}", "{{last_name}}", "{{title}}"])
+async def test_inbox_sequence_using_a_person_variable_is_rejected(var):
+ # "as General inbox at Acme" must never be rendered and sent.
+ steps = [
+ {"step": 1, "subject": "quick one", "body": f"Hi {var}, who answers at {{{{company}}}}?", "delay_days": 0},
+ {"step": 2, "subject": "following up", "body": "Still curious about {{company}}?", "delay_days": 3},
+ ]
+ assert await sequence_writer(steps)._write_sequence([inbox(industry="Roofing")]) == []
+
+
+async def test_inbox_sequence_with_company_only_is_kept():
+ steps = [
+ {"step": 1, "subject": "quick one", "body": "Hi there, who answers at {{company}}?", "delay_days": 0},
+ ]
+ out = await sequence_writer(steps)._write_sequence([inbox(industry="Roofing")])
+ assert [s.body for s in out] == ["Hi there, who answers at {{company}}?"]
diff --git a/tests/test_humanize.py b/tests/test_humanize.py
index a53f4df..ea4e6f9 100644
--- a/tests/test_humanize.py
+++ b/tests/test_humanize.py
@@ -7,15 +7,19 @@ from harvey.humanize import humanize, humanizer_enabled, load_skill
class FakeBrain:
- def __init__(self, reply):
+ """Returns ``reply`` for every call, or the next item of ``replies``."""
+
+ def __init__(self, reply=None, replies=None):
self.reply = reply
+ self.replies = list(replies or [])
self.prompts = []
async def think_json(self, prompt, **kwargs):
self.prompts.append(prompt)
- if isinstance(self.reply, Exception):
- raise self.reply
- return self.reply
+ reply = self.replies.pop(0) if self.replies else self.reply
+ if isinstance(reply, Exception):
+ raise reply
+ return reply
@pytest.fixture
@@ -46,7 +50,7 @@ async def test_no_skill_makes_no_call(tmp_path):
@pytest.mark.asyncio
async def test_good_rewrite_is_used(skill):
rewrite = {"subject": "after five", "body": "Hi {{first_name}}, who picks up the phone after five?"}
- brain = FakeBrain([rewrite])
+ brain = FakeBrain(rewrite)
out = await humanize(brain, [DRAFT], "writer", path=skill, enabled=True)
assert out == [rewrite]
assert "Cut the tells." in brain.prompts[0]
@@ -62,13 +66,14 @@ async def test_good_rewrite_is_used(skill):
])
@pytest.mark.asyncio
async def test_bad_rewrite_keeps_original(skill, bad):
- out = await humanize(FakeBrain([bad]), [DRAFT], "writer", path=skill, enabled=True)
+ out = await humanize(FakeBrain(bad), [DRAFT], "writer", path=skill, enabled=True)
assert out == [DRAFT]
@pytest.mark.asyncio
async def test_wrong_shape_or_failure_keeps_all(skill):
assert await humanize(FakeBrain([]), [DRAFT], "writer", path=skill, enabled=True) == [DRAFT]
+ assert await humanize(FakeBrain([DRAFT, DRAFT]), [DRAFT], "writer", path=skill, enabled=True) == [DRAFT]
assert await humanize(FakeBrain(None), [DRAFT], "writer", path=skill, enabled=True) == [DRAFT]
assert await humanize(FakeBrain(RuntimeError("down")), [DRAFT], "writer", path=skill, enabled=True) == [DRAFT]
@@ -76,14 +81,14 @@ async def test_wrong_shape_or_failure_keeps_all(skill):
@pytest.mark.asyncio
async def test_reply_without_subject(skill):
reply = {"subject": "", "body": "Sure, Thursday works. What time suits you?"}
- out = await humanize(FakeBrain([reply]), [{"subject": "", "body": "Sure! Thursday works for me. What time suits you best?"}], "handler", path=skill, enabled=True)
+ out = await humanize(FakeBrain(reply), [{"subject": "", "body": "Sure! Thursday works for me. What time suits you best?"}], "handler", path=skill, enabled=True)
assert out == [reply]
@pytest.mark.asyncio
async def test_installed_skill_alone_does_not_turn_it_on(skill):
# Installing the skill for Claude Code must not change what Harvey sends.
- brain = FakeBrain([{"subject": "after five", "body": "Hi {{first_name}}, who picks up?"}])
+ brain = FakeBrain({"subject": "after five", "body": "Hi {{first_name}}, who picks up?"})
assert await humanize(brain, [DRAFT], "writer", path=skill) == [DRAFT]
assert brain.prompts == []
@@ -113,3 +118,27 @@ def test_humanizer_is_off_by_default():
def test_humanizer_opt_in_from_config():
assert humanizer_enabled(_config(writer={"humanizer": True})) is True
+
+
+async def test_each_draft_is_rewritten_on_its_own(skill):
+ # One call per draft: a model can't hand one prospect's rewrite (with a
+ # real name and company in it) to another prospect by reordering.
+ alice = {"subject": "phones at beta", "body": "Hi Alice, who answers the phones at Beta Plumbing after five?"}
+ bob = {"subject": "phones at acme", "body": "Hi Bob, who answers the phones at Acme Roofing after five?"}
+ alice2 = {"subject": "beta after five", "body": "Hi Alice, who picks up at Beta Plumbing after five?"}
+ bob2 = {"subject": "acme after five", "body": "Hi Bob, who picks up at Acme Roofing after five?"}
+ brain = FakeBrain(replies=[alice2, bob2])
+ out = await humanize(brain, [alice, bob], "writer", path=skill, enabled=True)
+ assert out == [alice2, bob2]
+ assert len(brain.prompts) == 2
+ assert "Alice" in brain.prompts[0] and "Bob" not in brain.prompts[0]
+ assert "Bob" in brain.prompts[1] and "Alice" not in brain.prompts[1]
+
+
+async def test_rewrite_may_not_grow_past_the_draft(skill):
+ # A 39-word break-up email can't come back over the writer's 40-word cap.
+ draft = {"subject": "closing the loop", "body": " ".join(["word"] * 39)}
+ longer = {"subject": "closing the loop", "body": " ".join(["word"] * 45)}
+ assert await humanize(FakeBrain(longer), [draft], "writer", path=skill, enabled=True) == [draft]