Make the email body format explicit instead of guessing it from strings

Merged
FE
2d ago
+907-468

Stacked on twentyhq/twenty#30453.

Problem

An email body string meant three things (a serialized document, HTML or plain text), and every layer decided which by inspecting it with parseJson and looksLikeHtml. So 20 < 50 or a stray &amp; could change how a body was read and sent. The same guessing ran at every entry point: the email tools, proposals, the sendEmail mutation, the app channel send, workflow steps and the workflow editor.

Change

Explicit format, at the agent and app edge only. send_email, draft_email and propose_tool_call take an EmailBodyInput (twenty-shared), discriminated by type:

type EmailBodyInput =
  | EmailDocument                    // { type: 'doc', content: [...] }
  | { type: 'html'; html: string }   // sent as written: one htmlDocument block
  | { type: 'text'; text: string };  // paragraphs, \n → hard breaks

A bare string is rejected by the schema, and the tool description names the three shapes. convertEmailBodyInputToEmailDocument is the one conversion; the tools and buildEmailProposal call it. The dev seeder's proposed emails send { type: 'html' }.

Internal APIs only see documents, validated once:

  • composeEmail is the one place that validates an outbound document (parseEmailDocumentOrThrow), since approved tool calls reach the tools without schema validation. The sendEmail mutation only decodes the JSON; the app channel send parses it the same way. Anything else is INVALID_EMAIL_BODY.
  • One rule for versions: a document without attrs.schemaVersion is version 1 everywhere (tools, workflows, both mutations, the workflow editor).
  • Workflow steps: resolveInput resolves variables inside the stored document (so step logs, including failed ones, show the values used), and a toToolInput hook on ToolBackedWorkflowAction parses it for the tool. workflowSendEmailActionSettingsSchema enforces what its description says, so a non-document body fails when the step is saved, not when it runs; validateWorkflowStepParams relies on it instead of its own check.
  • Empty bodies are documents too. New send/draft email steps are created with an empty email document instead of '', and the editor form saves one when a step has none. The 2-59 workspace command backfill-empty-workflow-email-bodies stores it in existing steps whose body is a blank string, so nothing special-cases '' any more. A step with no body at all (the field is optional) sends the empty document.
  • The composer starts from a serialized empty document instead of ''.

looksLikeHtml leaves runtime code. It and the string-sniffing converter (convertEmailBodyToEmailDocument, convertStringBodyToEmailDocument, HTML_ELEMENT_NAMES) move unchanged into upgrade-version-command/2-47/utils/. The 2-47 workflow-body command is now their only user, as UPGRADE_COMMANDS.md asks for legacy formats only a command needs.

Breaking, accepted (no deprecation window)

  • Agents and apps must send { type: 'text' | 'html', … } or a document to send_email, draft_email and propose_tool_call. A matching Twenty for Twenty change (twentyhq/twenty-eng#760) sends { type: 'text', text }; ship them together.
  • The sendEmail and sendAppChannelMessage GraphQL mutations reject HTML and plain-text string bodies: body must be a serialized email document. The app docs (messaging-channels.mdx, inbox.mdx) now state this.
  • Workflow steps whose stored body is still an HTML or plain-text string (only possible for steps written outside the editor after 2-47 converted existing ones) fail with Invalid email document.
  • Rollout: until the 2-59 backfill reaches a workspace, a step with a blank stored body fails instead of sending an empty email. No fence: only steps that would send an empty body are affected, for that window.

Needs

  • ci:allow-previous-version-upgrade-mutation label. The move adds files under 2-47/ and rewires that command's import, which the upgrade mutation guard blocks by default. Command behaviour is unchanged: same code, now command-local.

Follow-up (not here)

  • Sending body as a JSON scalar on the sendEmail and app channel mutations, instead of a stringified document, needs GraphQL codegen against a running server.

Tests

  • Shared: the converter (text with CRLF and literal </&/{{…}}, HTML as written, a document stamped with its version), the schema rejecting a bare string or unknown type, and step validation accepting a document with or without a version and rejecting empty, HTML and text bodies.
  • Server: resolveEmailBody owns the parsing cases (strict parse, whole-body variable holding HTML or a document, rejection of blank and string bodies); the send and draft workflow actions (no body sends the empty document, an invalid body never reaches the tool, a failed draft logs the resolved body); the tool composing from the converted document; proposals with { type: 'text' } and a rejected bare string; the dev seeder's proposals resolving. The 2-47 converter spec moves with the code.
  • Front: the workflow body editor opening an unversioned document and not reading an HTML string.
  • Integration (outbound-email-body-formats): explicit tool bodies; one stored string body failing its step; whole-body variables as documents; the mutation accepting an unversioned document and rejecting a non-document; the 2-59 backfill (dry run, then both copies hold the empty document and the step sends).

Generated by Claude Code