feat(v1.1.7-email-outbound): SMTP send/send_html

Outbound email reachable from scripts as email::send(#{...}) (plain
text) and email::send_html(#{...}) (multipart text + HTML). Backed by a
lettre SMTP relay configured from PICLOUD_SMTP_HOST/PORT/USER/PASSWORD/
TLS/TIMEOUT_SECS; if HOST/USER/PASSWORD aren't all set the service runs
in disabled mode (every send throws NotConfigured, warned at startup).

- EmailService trait + OutboundEmail DTO (picloud-shared);
  EmailServiceImpl + EmailTransport seam + lettre transport
  (manager-core), wired into the Services bundle and Rhai engine.
- Capability::AppEmailSend (→ script:write); seven-scope commitment held.
- Required-field + RFC5322-ish address validation; 25 MB per-message cap
  (PICLOUD_EMAIL_MAX_MESSAGE_BYTES). reply_to defaults to from.
- Per-call connection (pooling deferred to v1.2); no per-app from
  validation (operator's SMTP/SPF/DKIM concern).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

crates/executor-core/src/sdk/email.rs

@@ -0,0 +1,150 @@
+//! `email::` Rhai bridge — outbound email (v1.1.7).
+//!
+//! ```rhai
+//! email::send(#{
+//!     to: "alice@example.com",   // String or Array of String
+//!     from: "alerts@myapp.com",
+//!     subject: "Build complete",
+//!     text: "Your deploy finished."
+//! });
+//!
+//! email::send_html(#{
+//!     to: ["alice@x.com", "bob@y.com"],
+//!     cc: ["dave@z.com"],
+//!     bcc: ["audit@myapp.com"],
+//!     from: "alerts@myapp.com",
+//!     reply_to: "support@myapp.com",   // optional; defaults to `from`
+//!     subject: "Build complete",
+//!     text: "Your deploy finished.",   // plain-text fallback
+//!     html: "<p>Your deploy <b>finished</b>.</p>"
+//! });
+//! ```
+//!
+//! Both map onto `EmailService::send`. `email::send` forces a text-only
+//! message (any `html` key is ignored); `email::send_html` requires an
+//! `html` part. `app_id` is derived from `cx.app_id` in the service.
+
+use std::sync::Arc;
+
+use picloud_shared::{EmailError, OutboundEmail, SdkCallCx, Services};
+use rhai::{Array, Engine as RhaiEngine, EvalAltResult, Map, Module};
+use tokio::runtime::Handle as TokioHandle;
+
+pub(super) fn register(engine: &mut RhaiEngine, services: &Services, cx: Arc<SdkCallCx>) {
+    let svc = services.email.clone();
+    let mut module = Module::new();
+
+    // email::send(#{...}) — plain text (html ignored).
+    {
+        let svc = svc.clone();
+        let cx = cx.clone();
+        module.set_native_fn("send", move |opts: Map| -> Result<(), Box<EvalAltResult>> {
+            let mut email = parse_email(&opts)?;
+            email.html = None; // text-only path
+            let svc = svc.clone();
+            let cx = cx.clone();
+            block_on(async move { svc.send(&cx, email).await })
+        });
+    }
+
+    // email::send_html(#{...}) — multipart text + html (html required).
+    {
+        let svc = svc.clone();
+        let cx = cx.clone();
+        module.set_native_fn(
+            "send_html",
+            move |opts: Map| -> Result<(), Box<EvalAltResult>> {
+                let email = parse_email(&opts)?;
+                if email.html.as_ref().is_none_or(String::is_empty) {
+                    return Err(runtime_err(
+                        "email::send_html: an 'html' field is required (use email::send for text-only)",
+                    ));
+                }
+                let svc = svc.clone();
+                let cx = cx.clone();
+                block_on(async move { svc.send(&cx, email).await })
+            },
+        );
+    }
+
+    engine.register_static_module("email", module.into());
+}
+
+/// Parse the Rhai options map into an [`OutboundEmail`]. Field-level
+/// validation (required fields, address shape) happens in the service;
+/// here we only do type coercion (String/Array → Vec<String>).
+fn parse_email(opts: &Map) -> Result<OutboundEmail, Box<EvalAltResult>> {
+    Ok(OutboundEmail {
+        to: addresses(opts, "to")?,
+        cc: addresses(opts, "cc")?,
+        bcc: addresses(opts, "bcc")?,
+        from: string_field(opts, "from").unwrap_or_default(),
+        reply_to: string_field(opts, "reply_to"),
+        subject: string_field(opts, "subject").unwrap_or_default(),
+        text: string_field(opts, "text"),
+        html: string_field(opts, "html"),
+    })
+}
+
+/// Read a string field. Missing or `()` → `None`.
+fn string_field(opts: &Map, key: &str) -> Option<String> {
+    match opts.get(key) {
+        None => None,
+        Some(d) if d.is_unit() => None,
+        Some(d) if d.is_string() => Some(d.clone().into_string().unwrap_or_default()),
+        // Coerce non-string scalars via display (numbers, etc.).
+        Some(d) => Some(d.to_string()),
+    }
+}
+
+/// Read an address list: a String becomes a one-element list; an Array
+/// of Strings becomes a list; missing/`()` is empty.
+fn addresses(opts: &Map, key: &str) -> Result<Vec<String>, Box<EvalAltResult>> {
+    match opts.get(key) {
+        None => Ok(Vec::new()),
+        Some(d) if d.is_unit() => Ok(Vec::new()),
+        Some(d) if d.is_string() => Ok(vec![d.clone().into_string().unwrap_or_default()]),
+        Some(d) => {
+            if let Some(arr) = d.clone().try_cast::<Array>() {
+                let mut out = Vec::with_capacity(arr.len());
+                for el in arr {
+                    if !el.is_string() {
+                        return Err(runtime_err(&format!(
+                            "email: '{key}' array must contain only strings"
+                        )));
+                    }
+                    out.push(el.into_string().unwrap_or_default());
+                }
+                Ok(out)
+            } else {
+                Err(runtime_err(&format!(
+                    "email: '{key}' must be a string or an array of strings"
+                )))
+            }
+        }
+    }
+}
+
+#[allow(clippy::unnecessary_box_returns)]
+fn runtime_err(msg: &str) -> Box<EvalAltResult> {
+    EvalAltResult::ErrorRuntime(msg.into(), rhai::Position::NONE).into()
+}
+
+/// Run an `EmailService` future inside the synchronous Rhai context,
+/// mapping any `EmailError` to a Rhai runtime error. Mirrors
+/// `kv::block_on`.
+fn block_on<F>(fut: F) -> Result<(), Box<EvalAltResult>>
+where
+    F: std::future::Future<Output = Result<(), EmailError>> + Send,
+{
+    let handle = TokioHandle::try_current().map_err(|e| -> Box<EvalAltResult> {
+        EvalAltResult::ErrorRuntime(
+            format!("email: no tokio runtime available: {e}").into(),
+            rhai::Position::NONE,
+        )
+        .into()
+    })?;
+    handle.block_on(fut).map_err(|err| -> Box<EvalAltResult> {
+        EvalAltResult::ErrorRuntime(format!("email: {err}").into(), rhai::Position::NONE).into()
+    })
+}

crates/executor-core/src/sdk/mod.rs

@@ -15,6 +15,7 @@ pub mod bridge;
 pub mod cx;
 pub mod dead_letters;
 pub mod docs;
+pub mod email;
 pub mod files;
 pub mod http;
 pub mod kv;
@@ -43,5 +44,6 @@ pub fn register_all(engine: &mut RhaiEngine, services: &Services, cx: Arc<SdkCal
     http::register(engine, services, cx.clone());
     files::register(engine, services, cx.clone());
     pubsub::register(engine, services, cx.clone());
-    secrets::register(engine, services, cx);
+    secrets::register(engine, services, cx.clone());
+    email::register(engine, services, cx);
 }

crates/executor-core/tests/module_redaction_logging.rs

@@ -102,6 +102,7 @@ async fn original_backend_error_is_logged_at_error_level() {
         Arc::new(picloud_shared::NoopFilesService),
         Arc::new(picloud_shared::NoopPubsubService),
         Arc::new(picloud_shared::NoopSecretsService),
+        Arc::new(picloud_shared::NoopEmailService),
     );
     let engine = Engine::new(Limits::default(), services);
 

crates/executor-core/tests/modules.rs

@@ -100,6 +100,7 @@ fn services_with(modules: Arc<dyn ModuleSource>) -> Services {
         Arc::new(picloud_shared::NoopFilesService),
         Arc::new(picloud_shared::NoopPubsubService),
         Arc::new(picloud_shared::NoopSecretsService),
+        Arc::new(picloud_shared::NoopEmailService),
     )
 }
 

crates/executor-core/tests/sdk_docs.rs

@@ -231,6 +231,7 @@ fn make_engine() -> Arc<Engine> {
         Arc::new(picloud_shared::NoopFilesService),
         Arc::new(picloud_shared::NoopPubsubService),
         Arc::new(picloud_shared::NoopSecretsService),
+        Arc::new(picloud_shared::NoopEmailService),
     );
     Arc::new(Engine::new(Limits::default(), services))
 }

crates/executor-core/tests/sdk_email.rs

@@ -0,0 +1,159 @@
+//! `email::` SDK bridge integration tests — runs a real Rhai engine
+//! against a recording `EmailService`. Verifies the Rhai map → DTO
+//! plumbing (address coercion, the text-only vs multipart split). The
+//! SMTP transport, validation, and authz are unit-tested at the service
+//! layer in `manager-core::email_service`.
+
+use std::collections::BTreeMap;
+use std::sync::{Arc, Mutex};
+
+use async_trait::async_trait;
+use picloud_executor_core::{Engine, ExecRequest, InvocationType, Limits};
+use picloud_shared::{
+    AppId, EmailError, EmailService, ExecutionId, NoopDeadLetterService, NoopDocsService,
+    NoopEventEmitter, NoopHttpService, NoopKvService, NoopModuleSource, OutboundEmail, RequestId,
+    ScriptId, ScriptSandbox, SdkCallCx, Services,
+};
+use serde_json::Value;
+
+#[derive(Default)]
+struct RecordingEmail {
+    sent: Mutex<Vec<OutboundEmail>>,
+}
+
+#[async_trait]
+impl EmailService for RecordingEmail {
+    async fn send(&self, _cx: &SdkCallCx, email: OutboundEmail) -> Result<(), EmailError> {
+        self.sent.lock().unwrap().push(email);
+        Ok(())
+    }
+}
+
+fn engine_with(rec: Arc<RecordingEmail>) -> Arc<Engine> {
+    let services = Services::new(
+        Arc::new(NoopKvService),
+        Arc::new(NoopDocsService),
+        Arc::new(NoopDeadLetterService),
+        Arc::new(NoopEventEmitter),
+        Arc::new(NoopModuleSource),
+        Arc::new(NoopHttpService),
+        Arc::new(picloud_shared::NoopFilesService),
+        Arc::new(picloud_shared::NoopPubsubService),
+        Arc::new(picloud_shared::NoopSecretsService),
+        rec,
+    );
+    Arc::new(Engine::new(Limits::default(), services))
+}
+
+fn baseline_request(app_id: AppId) -> ExecRequest {
+    let execution_id = ExecutionId::new();
+    ExecRequest {
+        execution_id,
+        request_id: RequestId::new(),
+        script_id: ScriptId::new(),
+        script_name: "email-test".into(),
+        invocation_type: InvocationType::Http,
+        path: "/email-test".into(),
+        headers: BTreeMap::new(),
+        body: Value::Null,
+        params: BTreeMap::new(),
+        query: BTreeMap::new(),
+        rest: String::new(),
+        sandbox_overrides: ScriptSandbox::default(),
+        app_id,
+        principal: None,
+        trigger_depth: 0,
+        root_execution_id: execution_id,
+        is_dead_letter_handler: false,
+        event: None,
+    }
+}
+
+async fn run(engine: Arc<Engine>, src: &str) -> Result<(), ()> {
+    let src = src.to_string();
+    let app = AppId::new();
+    tokio::task::spawn_blocking(move || engine.execute(&src, baseline_request(app)))
+        .await
+        .expect("spawn_blocking")
+        .map(|_| ())
+        .map_err(|_| ())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn send_parses_single_recipient_text() {
+    let rec = Arc::new(RecordingEmail::default());
+    let engine = engine_with(rec.clone());
+    run(
+        engine,
+        r#"
+        email::send(#{
+            to: "alice@example.com",
+            from: "alerts@myapp.com",
+            subject: "Build complete",
+            text: "done"
+        });
+        #{ ok: true }
+    "#,
+    )
+    .await
+    .unwrap();
+    let g = rec.sent.lock().unwrap();
+    let e = g.last().unwrap();
+    assert_eq!(e.to, vec!["alice@example.com".to_string()]);
+    assert_eq!(e.from, "alerts@myapp.com");
+    assert_eq!(e.subject, "Build complete");
+    assert_eq!(e.text.as_deref(), Some("done"));
+    // email::send forces text-only even if html were present.
+    assert!(e.html.is_none());
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn send_html_carries_both_parts_and_lists() {
+    let rec = Arc::new(RecordingEmail::default());
+    let engine = engine_with(rec.clone());
+    run(
+        engine,
+        r#"
+        email::send_html(#{
+            to: ["alice@x.com", "bob@y.com"],
+            cc: ["dave@z.com"],
+            bcc: ["audit@myapp.com"],
+            from: "alerts@myapp.com",
+            reply_to: "support@myapp.com",
+            subject: "hi",
+            text: "plain",
+            html: "<p>rich</p>"
+        });
+        #{ ok: true }
+    "#,
+    )
+    .await
+    .unwrap();
+    let g = rec.sent.lock().unwrap();
+    let e = g.last().unwrap();
+    assert_eq!(
+        e.to,
+        vec!["alice@x.com".to_string(), "bob@y.com".to_string()]
+    );
+    assert_eq!(e.cc, vec!["dave@z.com".to_string()]);
+    assert_eq!(e.bcc, vec!["audit@myapp.com".to_string()]);
+    assert_eq!(e.reply_to.as_deref(), Some("support@myapp.com"));
+    assert_eq!(e.text.as_deref(), Some("plain"));
+    assert_eq!(e.html.as_deref(), Some("<p>rich</p>"));
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn send_html_without_html_throws() {
+    let rec = Arc::new(RecordingEmail::default());
+    let engine = engine_with(rec.clone());
+    let res = run(
+        engine,
+        r#"
+        email::send_html(#{ to: "a@b.com", from: "c@d.com", subject: "x", text: "y" });
+        #{ ok: true }
+    "#,
+    )
+    .await;
+    assert!(res.is_err(), "send_html without html must throw");
+    assert!(rec.sent.lock().unwrap().is_empty());
+}

crates/executor-core/tests/sdk_files.rs

@@ -168,6 +168,7 @@ fn make_engine() -> Arc<Engine> {
         Arc::new(InMemoryFiles::default()),
         Arc::new(picloud_shared::NoopPubsubService),
         Arc::new(picloud_shared::NoopSecretsService),
+        Arc::new(picloud_shared::NoopEmailService),
     );
     Arc::new(Engine::new(Limits::default(), services))
 }

crates/executor-core/tests/sdk_http.rs

@@ -91,6 +91,7 @@ fn engine_with(http: Arc<dyn HttpService>) -> Arc<Engine> {
         Arc::new(picloud_shared::NoopFilesService),
         Arc::new(picloud_shared::NoopPubsubService),
         Arc::new(picloud_shared::NoopSecretsService),
+        Arc::new(picloud_shared::NoopEmailService),
     );
     Arc::new(Engine::new(Limits::default(), services))
 }

crates/executor-core/tests/sdk_kv.rs

@@ -110,6 +110,7 @@ fn make_engine() -> Arc<Engine> {
         Arc::new(picloud_shared::NoopFilesService),
         Arc::new(picloud_shared::NoopPubsubService),
         Arc::new(picloud_shared::NoopSecretsService),
+        Arc::new(picloud_shared::NoopEmailService),
     );
     Arc::new(Engine::new(Limits::default(), services))
 }

crates/executor-core/tests/sdk_pubsub.rs

@@ -48,6 +48,7 @@ fn make_engine(svc: Arc<RecordingPubsub>) -> Arc<Engine> {
         Arc::new(NoopFilesService),
         svc,
         Arc::new(picloud_shared::NoopSecretsService),
+        Arc::new(picloud_shared::NoopEmailService),
     );
     Arc::new(Engine::new(Limits::default(), services))
 }

crates/executor-core/tests/sdk_secrets.rs

@@ -101,6 +101,7 @@ fn make_engine() -> Arc<Engine> {
         Arc::new(picloud_shared::NoopFilesService),
         Arc::new(picloud_shared::NoopPubsubService),
         Arc::new(InMemorySecrets::default()),
+        Arc::new(picloud_shared::NoopEmailService),
     );
     Arc::new(Engine::new(Limits::default(), services))
 }

crates/executor-core/tests/sdk_subscriber_token.rs

@@ -95,6 +95,7 @@ fn make_engine() -> Arc<Engine> {
         Arc::new(NoopFilesService),
         Arc::new(FakeMintPubsub),
         Arc::new(picloud_shared::NoopSecretsService),
+        Arc::new(picloud_shared::NoopEmailService),
     );
     Arc::new(Engine::new(Limits::default(), services))
 }