[anukuljha]

PR 2 of 3 for channels v2. It is stacked on #1000 (PR 1) and targets that PR's branch; it should be retargeted to main once #1000 merges. It edits 0057 and 0058 in place, since neither has been released.

What changes

agent_surfaces becomes transport only. Every outbound send is a delivery row, the agent's answers included. The outreach policy moves into contacts, and what is heard reads as people and links rather than markup.

One outbound path

• Agent answers are lines first, then deliveries. A finished run's answer, or the failure notice for a failed run, is posted as the agent's line with client_message_id=run:{run_id} and deliver_to set to its place. The delivery executor then sends it.
  • Held files ride the answer, so email still folds into one reply.
  • A streamed Slack or Teams answer is finished in place, and its delivery is recorded SENT with the stream's message id. It is not posted a second time.
  • Web chat answers are SENT at once.
  • A run finished twice is one line and one send.
• Platform ids on every delivery. Each adapter's send_message returns the platform's id: the Slack ts, the Teams activity id, the Telegram message id, the WhatsApp wamid, or the Resend email id. It is recorded on the delivery row, for pushes as well.
  • Resend sends carry a per-delivery Idempotency-Key, so a retried delivery is the same email.
• Late failures by id. A WhatsApp status failure (131047, 131026, …) and a Resend email.bounced (permanent), email.complained or email.failed each mark the delivery DEAD by its platform id.
  • A permanent bounce or a complaint on a line to a contact also suppresses that address in the pod.
  • The Redis wamid-to-line map is deleted.
  • A temporary bounce, or an email that is not one of the channels', changes nothing.
• Send, then crash. A delivery claimed but never finished is not sent again. It becomes SENT when its platform id was noted before the call, otherwise DEAD (INTERRUPTED), which a member can retry. Each send is bounded at 60 s, under a 90 s claim lease.
• A place whose bot was removed is SKIPPED at once instead of retried.

Contacts policy (contacts.contracts.outreach)

• may_send(pod, contact, to, kind, at, window) returns a Verdict: allowed, plus a code, reason, retryable flag, footer and unsubscribe token. The order is suppression first, then whether a handle exists, then the window.
  • The per-contact daily count runs in Redis, is idempotent per line, and is counted once per line. Redis being unavailable is retryable, never final.
• Opt-out first, on every path. STOP is checked before any keeper, answer-policy or route check. It was being dropped silently for a contact with no keeper.
  • A whole-message STOP, an email whose whole subject is "unsubscribe", the email link, the one-click POST (RFC 8058), a permanent bounce or a spam complaint each write a contact_suppressions row. The row is keyed by the hashed handle, so it survives the contact being forgotten.
  • A suppression is lifted only by START or a message the person typed. Auto-replies (Auto-Submitted, out of office, Precedence: bulk) and unauthenticated mail never lift it.
• Normalised handles.
  • Phones are stored in E.164 via phonenumbers (contacts_default_phone_region).
  • Email addresses are trimmed and lower-cased.
  • Host identities are host:{issuer}:{sub}, with an issuer per web widget (host_issuer, set only at creation, because changing it would make every host contact a new one).
• Email to a contact carries List-Unsubscribe (https and mailto) and List-Unsubscribe-Post: List-Unsubscribe=One-Click.
• The WhatsApp 24-hour window stays a fact agent_surfaces supplies, read from the place's last_inbound_at: Meta keeps the window per business number and customer.

Ingest, threads and the contact inbox

• Markup becomes parts. The following become @Name mention parts and link parts:

  • Slack <@U…>, <url|label> and <#C|name>;
  • Teams <at> entities and <a href> links;
  • Telegram text_mention and text_link entities;
  • WhatsApp @<number> mentions.

  Each mention resolves to a member, a known contact, or the agent the bot answers for. A Slack user from another company in a shared channel resolves to their contact by user id.

  • Only people who may see the channel get an unread mention.

• Threads go home both ways. A reply written in Lemma under a platform thread is posted in it (Slack thread_ts, Teams ;messageid=). A platform reply to a line written in Lemma lands under that line. A top-level line goes to the place itself.

• Auto-acknowledge. Set with PodConfig.contacts.auto_acknowledge, where {pod} is replaced by the pod's name. When a contact's agents are off, the line is sent at most once per open period: a member writing, or the channel closing, starts a new one. It goes through may_send(ACK).

• Member-first outreach. POST /pods/{pod_id}/contacts/{contact_id}/outreach {handle, kind?, text, client_message_id?} writes to a contact first.

  • Email works any time and opens a place if needed. WhatsApp and Telegram only work at a place the contact wrote from, within its window.
  • The answer is the line and its delivery. A refusal is 409 when the address is suppressed, 422 outside the window, and 503 when Redis is unavailable.
  • Clients: SDKs PodContacts.outreach and ContactsNamespace.outreach; CLI lemma channels outreach.

• Hand-back. An assignee who hasn't written yet is held from assigned_at. Before, an explicitly assigned member was let go on the contact's very next message.

• Teams manifest 1.1.0 adds the RSC permissions PR 1 introduced. A test now pins a digest of the manifest per version, and the committed zip is rebuilt from the manifest.

Why

PR 2 of the channels v2 plan (#1000's description has the design). Design decisions D3 and D7: every outbound send is a delivery row, and agent_surfaces is transport only. The product rules come with them: STOP on every path, unsubscribe headers, thread routing, and member-first outreach.

Bugs found and fixed on the way

• STOP from a contact with no keeper was dropped silently, because the opt-out check ran after the keeper and route checks.
• apply_platform_update never committed when a lifecycle event was handled first, so WhatsApp status failures were not persisted.
• Every top-level member line to a Slack channel ended FAILED: at_place_level set external_thread_id=None, which failed validation.
• An explicitly assigned contact was handed back on the contact's next message, because assign() cleared assignee_last_line_at.
• The committed lemma-teams.zip had none of the RSC permissions, and make teams-manifest-zip called a script that doesn't exist.
• Every group-log line stored the platform's whole raw payload as its reply address. It now stores the event without raw_payload, which no reply reads.

How to verify

make quality            # 32 quality gates passed
make quality-frontend   # pass
make format-check       # pass
cd lemma-backend
uv run pytest app -m "not e2e" -n 8 -q        # 11674 passed, 153 skipped
uv run pytest app/modules/agent_surfaces/tests/e2e app/modules/channels/tests \
  app/modules/contacts/tests/e2e app/modules/workflow/tests/e2e/test_form_questions_e2e.py \
  app/modules/agent/tests/e2e/test_channel_answers_e2e.py \
  app/modules/agent/tests/e2e/test_channel_tools_e2e.py \
  app/modules/agent/tests/e2e/test_message_reply_delivery_e2e.py \
  app/modules/agent/tests/e2e/test_wait_work_e2e.py app/modules/pod/tests \
  -n 4 -q -m "not real_llm and not provider"   # 840 passed

Client suites: lemma-python 190 passed; lemma-cli 884 passed; lemma-typescript 463 passed; lemma-frontend 1556 passed.

New e2e tests:

• test_run_answer_deliveries_e2e.py: run finished twice; send-then-crash with and without the platform id; WhatsApp 131047 by wamid; a streamed Slack answer is one line and is not posted twice;
• test_email_bounces_e2e.py: a permanent bounce or a complaint marks the delivery DEAD and the next line is SKIPPED; a temporary bounce or an unknown email changes nothing;
• contacts/tests/e2e/test_outreach_e2e.py:
  • an opt-out holds across handle spellings and outreach kinds, and after the contact is forgotten;
  • opt-outs are scoped per pod;
  • the one-click POST suppresses;
  • the window and the daily count are enforced, and Redis being unavailable is retryable;
• test_handle_spelling_migration_e2e.py;
• test_channel_markup_threads_e2e.py: parts and mentions, visibility of mentions, Slack threads both ways, a Teams thread, a shared-channel outsider;
• test_contact_acknowledgement_e2e.py, test_contact_outreach_e2e.py, test_contact_hand_back_e2e.py;
• nine new STOP / START / auto-reply cases in test_contact_door_e2e.py.

Checklist

• Tests cover the behavioral change
• Lint, typecheck, and architecture gates pass locally
• Migrations:
  • 0057 adds contact_identities.issuer and value_raw, rewrites stored phones to E.164 and host values to host:default:…, moves unsubscribed_at into contact_suppressions, and adds agent_surface_web_widgets.host_issuer;
  • 0058 adds channels.acknowledged_at and channel_message_deliveries.claimed_at;
  • each has an upgrade and downgrade e2e.
• API surface: OpenAPI spec, both SDKs and lemma-client.js regenerated (outreach endpoint, host_issuer)
• Security: webhook events are verified with the Svix signature before anything is read; suppressions are stored hashed; an opt-out can't be lifted by an auto-reply or unauthenticated mail
• Rollback: revert, then downgrade 0058 and 0057; nothing has been released

Compatibility and rollback notes

• Configuration: surface_contact_follow_ups_per_contact_per_day is replaced by contacts_member_lines_per_contact_per_day. New: contacts_default_phone_region.
• Resend: the surfaces webhook (/surfaces/webhooks/resend) now also needs the email.bounced, email.complained and email.failed events. Identity's /auth/email/bounces/resend still deactivates accounts whose auth email bounces. Point Resend at both, or let both share one endpoint secret.
• Teams: the manifest is now 1.1.0, so an admin has to re-consent for the new RSC permissions.
• Not in this PR:
  • narration text sent with a question or approval card, and notices such as APPROVED_ACTION_FAILED_NOTICE, are no longer written as timeline lines (follow-up);
  • held WhatsApp replies and answers are now separate paths, so their order isn't enforced;
  • the Teams admin re-consent prompt in the product.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 97604175-fcf5-4c66-8d1e-341615c00942

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

CodeQL

No new findings on lines this pull request changed (as of b8adde1).

_{Updated on every push. A finding judged safe goes in .codeql-allow.txt with its reason, or is dismissed in the Security tab. GitHub Code Quality posts its own review comments separately.}

[github-actions]

Module	Unit	E2E only	Combined
Overall	73.2%	82.2%	91.5%
agent	78.7%	83.3%	92.8%
agent_surfaces	73.0%	82.9%	90.8%
apps	75.7%	87.6%	92.4%
connectors	78.7%	73.6%	90.2%
datastore	69.0%	86.4%	90.9%
function	70.2%	87.6%	92.8%
icon	88.8%	77.1%	89.6%
identity	64.4%	86.3%	92.5%
pod	62.3%	89.6%	92.1%
pod_bundle	75.8%	69.5%	88.2%
schedule	63.5%	89.0%	91.7%
usage	74.4%	84.5%	91.9%
workflow	70.1%	82.9%	89.8%
workspace	79.4%	59.4%	86.8%

[deepak-jha-kgp]

Factory review: Changes needed

round 2 · reviewed at a0af76d · updated 20 Oct, 04:44 UTC · waiting on @anukuljha · high risk

Every line that leaves a pod takes one path out

• Before: Each service that sent a line to a place or to a member planned its own delivery row, decided its own rules for writing to a contact, and recorded the outcome its own way: contact_rules.py held one caller's version of those rules, and PlatformDeliverySender posted whatever it was handed.
• After: A line's send is one delivery row, planned before anything is sent, claimed under a lease by one worker and settled with an outcome on that row; every write to a contact passes one policy first — opt-out, then a handle, then the platform's window — with the contact's day counted once in Redis however often a send is retried.

What could break

• If any environment has already run revision 0058_channels (main carries it from Channels: one timeline per place; one conversation per person and agent #993), then editing the file in place means Alembic never re-runs it, so channel_cases, channel_case_events, channels.current_case_id and external_accounts.workspace_key never appear — and every channels request fails on them. (medium likelihood, high impact; guard: none — no test upgrades a database that already ran main's 0058)
• If a contact opted out before the migration and their handle was stored with a leading 00, a space or a bracket, then the suppression row 0057 writes is keyed by the hash of that spelling while may_send looks it up by the hash of the normalised handle, so the pod writes to somebody who asked it to stop. (medium likelihood, high impact; guard: none — the unit tests cover decide() and may_send() with already-normalised handles, not the migration)
• If a sender dies between claiming a row and recording the outcome, the row is settled DEAD with INTERRUPTED and is never sent again blind: the message may be on the platform already, or may not, and only a member retrying the row resolves it. (medium likelihood, medium impact; guard: DeliveryRepository.interrupted() and the reclaim path for platforms that dedupe on the delivery's key; test_channel_delivery_races_e2e.py)

299 of 67,793 changed lines worth reading. The rest is mechanical, generated or lockfiles.

Decisions this PR makes

1. Migrations 0057 and 0058 are edited in place although main already carries both revision ids — Alembic records a revision as applied (lemma-backend/migrations/versions/2026-10-17_channels_0058.py)
2. The migration hashes the handle as it is stored, while every lookup hashes the normalised handle — An opt-out written by 0057 is keyed by sha256 of the stored spelling; may_send and SuppressionRepository key everything through handle_hash, which normalises first (lemma-backend/migrations/versions/2026-10-17_contacts_for_everyone_0057.py)
3. Every outbound send is one delivery row claimed under a lease, and a lapsed claim is never retried blind — If a sender dies mid-send the row becomes DEAD/INTERRUPTED rather than being sent again, so a message may be on the platform and marked not delivered, or lost, and only a member can retry it (lemma-backend/app/modules/channels/infrastructure/deliveries.py)
4. A run's answer closes its live stream in place and reuses that message as the delivery — On Slack the answer has been streaming into one message (lemma-backend/app/modules/agent_surfaces/services/run_answer_sends.py)
5. All writing to a contact passes one policy in one order, with the day counted in Redis — Opt-out first (lemma-backend/app/modules/contacts/domain/outreach.py)

Findings · 2 open · 1 settled

• 0057 keys each opt-out by the stored spelling, but every lookup keys it by the normalised handle — lemma-backend/migrations/versions/2026-10-17_contacts_for_everyone_0057.py:83
• 0058 is edited in place although main already carries revision 0058_channels — lemma-backend/migrations/versions/2026-10-17_channels_0058.py:701

Worth fixing · 2 warnings

1. 0057 keys each opt-out by the stored spelling, but every lookup keys it by the normalised handle — lemma-backend/migrations/versions/2026-10-17_contacts_for_everyone_0057.py:83-93

The migration writes suppressions as sha256(convert_to(value, 'UTF8')) over the value it just rewrote (0057.py:90-93), and only rewrites a phone when it is all digits (value ~ '^[0-9]+$', 0057.py:83-84). Every runtime lookup goes through handle_hash, which normalises first (handles.py:115 → normalize_handle → e164, handles.py:55). So for a handle the migration did not canonicalise the two keys differ and the opt-out is invisible: e164("0044790000123") returns +44790000123 while the migration stores +0044790000123; a value stored as +1 (415) 555-0100 is not touched at all and hashes as its punctuated self, while lookups hash +14155550100. The person who unsubscribed before the migration is written to again by every sender, because may_send (contacts/services/outreach.py:68) and decide (contacts/domain/outreach.py:114) find no suppression for them.

Suggested fix:

Spell the values the way the code spells them before hashing, or hash the way the code hashes: `UPDATE contact_identities SET value = ...` for every phone through the same rule, then `INSERT ... SELECT pod_id, kind, sha256(convert_to(<the normalised value>, 'UTF8')) ...`. A one-line guard test that a migrated row's `value_hash` equals `handle_hash(kind, value)` would pin it.

2. 0058 is edited in place although main already carries revision 0058_channels — lemma-backend/migrations/versions/2026-10-17_channels_0058.py:701-749

origin/main has migrations/versions/2026-10-17_channels_0058.py with revision = "0058_channels" and down_revision = "0057_contacts_for_everyone" (added by #993), and this diff edits the same file under the same revision id (blob 39d1fb9a on main, 2edbc5b8 here). Alembic stores a revision as applied, so any database that already ran main's 0058 keeps the old schema: the new tables channel_cases (0058.py:102) and channel_case_events (0058.py:138), and the new columns channels.current_case_id, channels.last_rev, channels.changed_rev, external_accounts.workspace_key/bot_key and channel_messages.parts, are never created there, and every channels query fails with UndefinedColumn/UndefinedTable. The same applies to 0057, which this diff also edits (blob 5cd35cd0 on main, b3e942f0 here) — its new contact_identities.issuer, value_raw and contact_suppressions rows would never appear on such a database. On the factory's own note: this finding is a repeat of an open one, kept because it is still true at this commit and now larger.

Suggested fix:

Either add a new revision after main's 0058 that creates the missing tables and columns, or confirm in the PR body that no environment has run 0058_channels and 0057_contacts_for_everyone (and delete the old rows from alembic_version if one has).

• A retried outreach call that names a different handle unpacks an empty list and answers 500 — fixed

Rounds

#	When	Commit	What	Verdict
1	19 Oct, 09:17 UTC	fdde613	full read	Needs a person's review
2	20 Oct, 04:44 UTC	a0af76d	full read	Changes needed

One comment, edited after every round. Last updated 20 Oct, 04:44 UTC.