Skip to content

feat(replies): draft cited replies to imported email - #565

Merged
adeelahmad merged 10 commits into
mainfrom
claude/project-thread-4cz7ul
Oct 18, 2026
Merged

adeelahmad merged 10 commits into
mainfrom
claude/project-thread-4cz7ul

Conversation

@adeelahmad

@adeelahmad adeelahmad commented Oct 18, 2026 •

Copy link
Copy Markdown
Owner

Requested by Adeel · project thread

Description

Before: email a watched Gmail or IMAP mailbox brought in was searchable and citable, but nothing helped answer it.

After: Lens drafts a reply to an email from what that email's namespace holds. Each fact is cited [n] to the excerpt it came from, anything the archive doesn't say is written in as [to confirm: …] and listed as a gap, and the draft is addressed to the sender (or their Reply-To), from the mailbox it came in to, with In-Reply-To and References so it threads. Drafts wait to be edited or set aside (undo by setting them back). Nothing is sent.

How: a new job step, reply (app/domain/responder.py), modelled on spec. It reads the message again from its source (ingest.audio_path plus keyring.open_plain), strips the quote and signature with mailbox.split, finds excerpts with chat.retrieve limited to the email's own namespace (and never the email itself), and asks the model through a prompt template, Reply to an email, which is seeded at startup and can be edited on the Templates page. The result is stored in a new email_reply table keyed by recording; it is deleted and moved along with its email.

  • API: GET /replies (mail that waits: not lists, no-reply senders or your own, plus every draft), POST/GET/PATCH /recordings/{id}/reply.
  • MCP: email_replies, draft_reply (with instructions), get_reply, edit_reply.
  • Pipelines: the reply step is available in the editor and canvas. No pipeline has it by default. When a pipeline runs it, automatic mail and your own mail are skipped without a model call.
  • Safety: the email reaches the model marked untrusted, and the system prompt says not to follow it. Links in the draft that neither the email nor the excerpts contain get broken up, and citations to excerpts the model wasn't given are removed. There's a threat-model entry for this (prose, YAML and JSON).

Sending through the mailbox, after the person says yes, comes in a follow-up that reuses the Gmail write half (#552). A Replies page in the web app also comes in a follow-up.

Motivation and Context

This is the flagship consumer app on Lens infrastructure (Adeel, 2026-10-05: infrastructure first, then an email responder). It is built on the existing Gmail and IMAP sensors, the job pipeline, templates, retrieval and the untrusted-text defences.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change; ! in the title)

Checklist:

  • The title is a Conventional Commit.
  • My code follows the code style of this project (make hooks checks it on commit).
  • I added or updated tests.
  • My change requires documentation updates, and I have updated docs/ accordingly.
  • Users need more than the title to understand it, so I wrote it in changelog.d/email-replies.md.

Done questions (AGENTS.md)

  • Goal: the first step of the email responder (drafts, review, agents). Sending and the web page follow in their own PRs. Merged on green.
  • Agents: four MCP tools plus the REST API.
  • Zero setup: uses the configured LLM and any existing mail source. Nothing new to install.
  • Fewest clicks: one call drafts a reply. A pipeline step drafts every new email. Undo by setting the status back, with no confirm dialog. (The web page comes next.)
  • Configurable: the prompt is an editable template, and the step is added per pipeline in the web app. No new settings.
  • Light: one model call per drafted email, through the existing job workers. Nothing heavy.
  • Private and secure: only the email's own namespace is searched, the email is marked untrusted, foreign links are broken up, and nothing is sent. Threat model entry added.
  • Cost: runs as a job, so budgets and the activity ledger apply. Pipelines skip automatic and own mail with no model call.
  • User decides: nothing is sent, and drafts wait for the person. Off by default (no pipeline has the step). Existing defaults are unchanged.
  • Upgrades: a new table with no change to existing data. The template is seeded idempotently on start.
  • Honest: drafts cite their sources and mark gaps. README lists only what's merged, and the docs mark sending as refine-later.
  • Tests, docs and generated files: tests/api/test_replies.py (4 tests), docs/email-replies.md, requirements rows, make openapi output.
  • Open standards: RFC 5322 threading headers. No new dependencies.
  • Reported in the project thread. Refine-later items are in the module docstring and the docs.
  • Reuse: the spec step pattern, mailbox.split/automatic, chat.retrieve/excerpts, untrusted.mark/defang, and templates.

Local checks: backend suite, ruff, mypy, tsc, prettier, pipeline jest, ci/check_requirements.py, ci/validate_threat_model.py --base origin/main, mkdocs build --strict, and ci/local-ci.sh --pr 565.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Xa7Hz2SLg6sNrGksMEzBaz

A reply step drafts a reply to an email from its own namespace's excerpts,
each fact cited, gaps marked to confirm, addressed and threaded. Drafts wait
for the person; nothing is sent. API, MCP tools, pipeline step, template,
docs, requirements and threat model.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xa7Hz2SLg6sNrGksMEzBaz
@adeelahmad adeelahmad self-assigned this Oct 18, 2026
…-4cz7ul

# Conflicts:
#	docs/mcp.md
#	fastapi_backend/app/api/v1/router.py
#	nextjs-frontend/app/openapi-client/index.ts
#	nextjs-frontend/app/openapi-client/sdk.gen.ts
#	nextjs-frontend/app/openapi-client/types.gen.ts
#	nextjs-frontend/openapi.json
#	threat-model.json
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xa7Hz2SLg6sNrGksMEzBaz
Also lists the assistant's answers about Lens itself (#400, released in
v0.15.0) as built, which check_requirements now asks for.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xa7Hz2SLg6sNrGksMEzBaz
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xa7Hz2SLg6sNrGksMEzBaz

Copy link
Copy Markdown
Owner Author

Clicks and keystrokes per feature failed on the phone survey only: chat-research timed out waiting for the research plan card. The same journey passed on a computer in this run.

I don't think this PR caused it. Its diff doesn't touch chat, research or the stand-in model (ci/clicks/fake-model.mjs). The same phone chat journeys fail on unrelated PRs over the same window:

  • chat-research on run 39108332113;
  • chat-ask on runs 39108279757 and 39108209701.

No fix exists yet. I've re-run the failed job once and will look into the phone chat timeout if it fails again.


Generated by Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xa7Hz2SLg6sNrGksMEzBaz
…-4cz7ul

# Conflicts:
#	README.md
#	docs/requirements.md
…and JSON

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xa7Hz2SLg6sNrGksMEzBaz
…-4cz7ul

# Conflicts:
#	docs/mcp.md
#	nextjs-frontend/components/pipelines/pipeline-canvas.tsx
@adeelahmad
adeelahmad merged commit 8f29f1d into main Oct 18, 2026
12 of 13 checks passed
@adeelahmad
adeelahmad deleted the claude/project-thread-4cz7ul branch October 18, 2026 13:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants