[Silthus]

Problem

Feature flags. workflows-email-reach gates the recipient-eligibility API and MCP discovery. Site-link guidance remains unconditional.

AI-created workflow emails can contain placeholder links and leave users unsure who can receive them or what to do next.

Warning

🟡 Merge risk: medium (merge-risk rubric)

• The new aggregate API reads tenant data. Workflow resource access, person/integration read scopes, and cross-tenant tests limit exposure.
• Eligibility totals do not predict future event-triggered sends. The tool and skill state that distinction.

Fork handoff for source #111750. Modernized head 718592f888d88e7433e383f2cc4e4c22093c3feb. This draft prepares review and recreation in the upstream repository.

Changes

Kind	Files	Lines
Production	2274	+116676 −26293
Tests	963	+72695 −18200
Evals	22	+671 −200
Docs	171	+5605 −3146
Generated	87	+9586 −965
Total	3517	+205233 −48804

• Guide the agent to use configured project URLs, with recent pageviews as a fallback, and update sequence links in one follow-up.
• Require a handoff that names the URL, shows sender eligibility counts, and ends with testing and enabling steps.
• Keep email guidance in a required reference with ordered steps and completion checks for links, reach, and the handoff.
• Add one shared read-only eligibility endpoint and MCP tool for the agent and first-run screens, including safe sender verification metadata.

How did you test this code?

Test seams: The public email-reach API catches incorrect verification, inactive members, empty emails, missing scopes, cross-tenant counts, sender metadata exposure, and restricted email access. The existing resource-permission API test covers both audience endpoints. New endpoint behavior, sender metadata, and restricted-email denial each failed before implementation.

Verification commands:

.codex/with-flox hogli test products/workflows/backend/tests/api/test_email_reach.py
.codex/with-flox hogli test products/workflows/backend/tests/api/test_hog_flow_access_control.py -k audience_counts_require_resource_level_access
.codex/with-flox env CI=1 pnpm --filter=@posthog/mcp exec vitest run tests/unit/tool-schema-snapshots.test.ts

All ten endpoint tests and both resource-access tests passed against Postgres and ClickHouse, including after the master merge. A seeded local project with app_urls configured returned HTTP 200 from the final endpoint, including both counts and email_senders.

OpenAPI generation, Python lint and formatting, commit-hook ty, both TypeScript checks, focused security scan, and full repository mypy passed. Strict pre-push checks passed. Skill lint and build passed after reorganizing the email guidance; no new prose-only tests were added.

The MCP runtime schema test failed without the new snapshot, then passed after generating that one file. No existing snapshots changed.

After merging master 249f31f8b88 on e862639bfe3, frontend and MCP production builds and both TypeScript checks passed. Rebuilding stale quill primitives resolved a local type error.

The architecture linter caught a direct service import. Routing it through the existing email-health facade passed all six contracts and preserved the API response.

The email-reach, resource-access, and focused email-health tests passed. OpenAPI regeneration produced no drift; skill lint/build and strict preflight passed. The final merge has both the prior PR head and master as parents.

The CI patch-coverage artifact is unavailable pending maintainer approval. API tests exercise the new production paths; generated clients and skill guidance use generation and contract checks.

New-events-schema requirements do not apply: no event-reading code changed, and the new count test reads persons.

The live AI-first composer run, generated CTA, final answer, and follow-up URL replacement remain unverified. The local stack has no LLM gateway key; this gap is accepted for review. No UI components or layouts changed; frontend edits are generated API types and clients. Screenshots of the generated CTA and chat answer require that live run.

Modernization on 3b1acf11e4f7b: The new workflows-email-reach flag gates the API and MCP tool. Disabled or failed flag evaluation returns 403 before count queries. Existing permission and scope checks still apply. The final API/access-control suites, full OpenAPI generation, MCP code generation and strict preflight passed. Historical proof describes earlier heads; fresh CI and companion review remain unchecked.

Final freshness on 718592f888d88e7433e383f2cc4e4c22093c3feb against upstream master b75567aca6cce9f0499e882463fc7e71d65a064c: 69 backend and 72 frontend cases, full frontend TypeScript and strict preflight passed; full OpenAPI regeneration produced zero tracked drift. Upstream zoom behavior preserved while rebasing canvas preview sizing. Exact leases and ordinary pre-push gate verified. Prior proof remains historical. Fresh upstream CI and companion review remain unchecked.

Release status

Fork handoff only. This task does not activate rollout flags. Upstream CI and the unavailable Opus review remain handoff gaps.

The new recipient-eligibility API and MCP discovery require workflows-email-reach. Site-link guidance and existing HTTPS safety checks remain unconditional. No rollout flag was activated by this task.

• This change includes feature-flagged behavior. The API and MCP tool require workflows-email-reach; site-link guidance is unconditional.

• Publish to changelog?

Docs update

Updated the existing workflow email sending guide with the API fields, permissions, and eligibility semantics.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Agent: T3 Code through Codex, gpt-6.1-sol

Session: Local T3 thread mcp:ffe68f3b-bb13-422d-9ee5-eeb567b6aeb7. No public transcript URL is available.

Tools used: local shell, Git, gh, native Codex reviewers, and T3 PR linking and delegated Claude reviews.

The scope covers site links, recipient eligibility and the draft handoff. Email layout and model selection remain separate. The count API is shared with the first-run work rather than duplicated. Existing related drafts implement sender restrictions and batch warnings; none supplies this shared count endpoint.

Open-PR searches for workflow email reach and sandbox work found related sender and batch-warning PRs, but no duplicate reach endpoint.

Sandbox delivery enforcement is separate and absent on this base. The guidance applies its count only when that sender exists; Maildev means local inbox delivery.

Skills applied: /tdd, /qa-swarm, /writing-tests, /integrating-with-posthog-ai, /implementing-mcp-tools, /improving-drf-endpoints, /writing-dataclasses, /writing-pr-descriptions, /run-posthog, /running-ci-preflight, /merge-risk, /writing-user-facing-copy, /writing-voice, /writing-for-agents, /writing-skills, /resolving-merge-conflicts, and /unslop.

Local CodeRabbit was skipped because its CLI is signed out. Cross-model QA fixed sender classification, unsupported sender assumptions, caller-specific property access, a removed fallback tool, and a missing schema snapshot/catalog entry. Round four was clean on 8e91f8ef2c2: all six GPT-6.1 Sol lenses and Claude Opus 5.5 covered all 16 implementation files. The prose-only follow-up on 49323ca5fdc uses the swarm's bot-and-check path. Claude Opus 5.5 reviewed the master merge; its facade-import finding was reproduced and fixed on f376a9b0c48. Upstream CI requires maintainer approval, so the QA handoff remains blocked on that external check gap.

Fixtures use invented addresses on example.com. No customer data or other private session material is included in public artifacts.

Modernization: T3 Code, Codex, gpt-6.1-sol. Skills: modernize-pr, pr, writing-pr-descriptions, writing-voice, unslop, running-ci-preflight. A fresh Claude Opus 5.5 review attempt hit an API rate limit; the modernization review remains incomplete.

[github-actions]

🤖 CI report

ℹ️ MCP agent API — agent-facing tool changes

What this PR changes for agents, from the tool schema snapshots and tool definitions.

Tools added (1): workflows-email-reach (33 chars)

[Silthus]

Closing: the new workflow editor replaced the surface this changes, so this stack is obsolete.