from html import escape DEBUG_REASON_MARKERS = ( "step passes", "classifier", "rule evaluation", "no handoff instructions were set", ) def _clean_external_subject(subject: str) -> str: value = (subject or "(No subject)").strip() for prefix in ("Re: ", "RE: ", "re: "): if value.startswith(prefix): value = value[len(prefix) :].strip() for prefix in ("Human Handoff · ", "Human Handoff: "): if value.lower().startswith(prefix.lower()): value = value[len(prefix) :].strip() return value or "(No subject)" def handoff_email_subject(external_subject: str) -> str: return f"Human Handoff · {_clean_external_subject(external_subject)}" def external_reply_subject(external_subject: str) -> str: cleaned = _clean_external_subject(external_subject) return f"Re: {cleaned}" def format_reason_for_human(reason: str | None, *, is_update: bool = False) -> str | None: if is_update: return None if not reason or not reason.strip(): return None lower = reason.strip().lower() if any(marker in lower for marker in DEBUG_REASON_MARKERS): return "This conversation matched your Human Handoff settings." if lower in { "matched handoff rules.", "new message in the linked conversation.", }: return "This conversation requires human attention." return reason.strip() def build_initial_handoff_text( *, external_sender: str, external_subject: str, external_body: str, agent_email: str, handoff_reason: str | None, ) -> str: reason = format_reason_for_human(handoff_reason) lines = [ "GENTIC — HUMAN HANDOFF", "", "This conversation needs your attention.", "", f"From: {external_sender}", f"Subject: {_clean_external_subject(external_subject)}", "", "LATEST MESSAGE", "", external_body.strip(), "", ] if reason: lines.extend(["WHY YOU'RE RECEIVING THIS", "", reason, ""]) lines.extend( [ "REPLY NORMALLY", "", f"Reply to this email and Gentic will send only your new reply to the " f"original sender through {agent_email}.", "", "This private handoff conversation and quoted history will not be shared " "with the sender.", "", "—", "Gentic Human Handoff", "Private Agent ↔ Human conversation", ] ) return "\n".join(lines) def build_initial_handoff_html( *, external_sender: str, external_subject: str, external_body: str, agent_email: str, handoff_reason: str | None, ) -> str: reason = format_reason_for_human(handoff_reason) reason_block = "" if reason: reason_block = f"""

Why you're receiving this

{escape(reason)}

""" return f"""
{reason_block}

✦ Gentic

Human Handoff

This conversation needs your attention.

From

{escape(external_sender)}

Subject

{escape(_clean_external_subject(external_subject))}

Latest message

{escape(external_body.strip())}

↩ Reply normally

Reply to this email and Gentic will send your response to the original sender as {escape(agent_email)}. Only the new text you write will be sent. This handoff email and quoted history stay private.

Gentic Human Handoff
Private Agent ↔ Human conversation

""" def build_update_handoff_text( *, external_sender: str, external_body: str, agent_email: str, ) -> str: return "\n".join( [ "Customer replied", "", external_sender, "", external_body.strip(), "", f"Reply normally to respond through {agent_email}.", ] ) def build_update_handoff_html( *, external_sender: str, external_body: str, agent_email: str, ) -> str: return f"""

✦ Gentic

Customer replied

{escape(external_sender)}

{escape(external_body.strip())}

Reply normally to respond through {escape(agent_email)}.

""" def build_relay_confirmation_text(customer_body: str) -> str: return f"Sent to customer:\n\n{customer_body.strip()}"