feat: agent-optimized v0.2.0 — composite tools + verification + gating#5
Merged
feat: agent-optimized v0.2.0 — composite tools + verification + gating#5
Conversation
Adds the agent-facing composite-tool surface that lets Claude (or any MCP
client) drive Leadbay end-to-end without the agent needing to know about
lens permissions, region routing, polling, or selection state. Designed
through a full /autoplan dual-voice review (CEO + Eng + DX) followed by
live API exploration; all 29 approved revisions are in this PR.
New composite tools (agent's default surface):
- pull_leads (replaces find_prospects; adds qualification_summary per lead)
- research_lead (qualification → signals → firmographics → contacts → engagement)
- bulk_qualify_leads (paginates past already-qualified, fan-out + poll, 429 mid-fanout)
- enrich_titles (selection-lifecycle managed, dry_run, 429 handling)
- adjust_audience (admin/non-admin auto-routing, sector free-text resolution, draft fallback)
- refine_prompt + answer_clarification (admin-gated, stale-clarification guard)
- recall_ordered_titles (preview-field path + live-aggregate fallback)
- account_status (quota + admin + intelligence state)
- report_outreach with mandatory verification (gmail_message_id | calendar_event_id | user_confirmed) — prevents pipeline poisoning
New granular tools (28): lens filter/scoring/draft/promote/create/update/active,
selection select/deselect/clear/ids, sectors taxonomy, user_prompt CRUD,
clarifications get/pick/dismiss, epilogue set/remove + responses, prospecting actions,
notes read, web_fetch read, bulk-enrichment preview/launch.
Client refactor: HTTP header capture, _meta envelope (region + endpoint +
latency_ms + retry_after), 429→QUOTA_EXCEEDED mapping (was RATE_LIMITED),
60s /me cache with invalidateMe() called by every write tool that mutates
cached fields, selection Mutex (for concurrent enrich_titles), region
auto-detect on login (us → fr fallback).
Gating model:
- LEADBAY_MCP_WRITE=1 — exposes composite + granular write tools (off by default)
- LEADBAY_MCP_ADVANCED=1 — exposes granular API tools (off by default)
- OpenClaw plugin: exposeWrite + exposeGranular config flags (both off by default)
- leadbay_login still hidden from MCP (UC-3, prompt-injection vector)
Mock mode (LEADBAY_MOCK=1) reads fixtures from .context/leadbay-live-shapes/
for agent-author dry-running. dry_run param on every state-changing composite.
Tests: 89 unit (54→58 core, 11→12 leadclaw, 19 mcp), 10 live read-only smoke,
plus end-to-end MCP and OpenClaw plugin live smokes against the real backend.
Per-tool description style enforced ("When to use" + "When NOT to use" sections).
Live-probe drift documented in .context/leadbay-live-shapes/SHAPE-DRIFT.md
(gitignored). Migration notes in packages/mcp/MIGRATION.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
6 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the agent-facing composite-tool surface that lets Claude (or any MCP client) drive Leadbay end-to-end without needing to know about lens permissions, region routing, polling, selection state, or quota mechanics. Designed through a full /autoplan dual-voice review (CEO + Eng + DX, both Codex and Claude subagent voices) followed by live API exploration against production. Ships 10 composite agent-skill tools (
pull_leads,research_lead,bulk_qualify_leads,enrich_titles,adjust_audience,refine_prompt,answer_clarification,recall_ordered_titles,account_status,report_outreach) plus 28 new granular API tools, all gated byLEADBAY_MCP_WRITE=1/LEADBAY_MCP_ADVANCED=1(MCP) orexposeWrite/exposeGranularplugin config (OpenClaw);report_outreachrequiresverification: {source: gmail_message_id|calendar_event_id|user_confirmed, ref}to prevent hallucinated outreach poisoning the SDR pipeline (cross-phase critical from the review). Client refactored with HTTP header capture, region+latency+retry_after_metaenvelope,429→QUOTA_EXCEEDEDmapping (production behavior), 60s/mecache withinvalidateMe()called by every cached-field mutator, selection Mutex, region auto-detect on login (us → fr fallback). Tests: 89 unit (54+11+19 → 58+12+19), 10 live read-only smoke, plus end-to-end MCP and OpenClaw plugin live smokes — all 100% pass against the real backend.Test plan
pnpm test— 89 unit tests pass across all 3 packagespnpm test:smokewith token — 10 live read-only smoke tests pass againstapi-us.leadbay.appaccount_status→pull_leads→research_lead→recall_ordered_titles→report_outreach(dry_run + verification rejection) →get_lens_filter→list_sectors→get_quotaagainst the real backend, scans every response and log line for credential leaksexposeWrite=trueexposes them, full live flow worksexposeGranular+exposeWriteare on).context/and.claude/gitignored; the literal "Password1!" coincidence in a doctring removed)See
packages/mcp/MIGRATION.mdfor the v0.1 → v0.2 upgrade guide.🤖 Generated with Claude Code