loopengine 0.1.91 → 0.1.93

package/README.md

@@ -157,7 +157,7 @@ Six channels ship as real, working notifiers — configure one and the
 | `webhook` | Signed HMAC-SHA256 POST to any URL you own |
 | `slack` | An interactive message via `chat.postMessage`, with Approve/Deny buttons |
 | `lark` | A Lark/Feishu interactive card |
-| `email` | A signed, expiring magic-link per decision |
+| `email` | An email per decision, through your own `sendEmail`: with signed, expiring magic links to your endpoints, or a link to this server's decision page |
 | `database` | Writes a row for your own worker/dashboard to poll |
 | `redis` | Pushes a queue entry for your own worker to consume |
 
@@ -173,7 +173,9 @@ export const config: AgentConfig = {
 ```
 
 Or skip the code: in the console, the agent's **Messaging** tab sets a
-webhook, Slack or Lark target for one agent (saved to
+webhook, Slack, Lark or email target for one agent (email sends through
+Resend, SendGrid or Postmark with your API key, each email linking to the
+decision page) (saved to
 `agents/<name>/messaging.yml`, with its secret in the agent's own `.env`;
 an older `notifier.yml` is still read), sends a test and shows recent
 deliveries. With Slack, people can also reply in a request's thread to
@@ -205,6 +207,14 @@ first, and a paused schedule if it runs on a timer, plus a checklist of
 what's left to connect. The interviewer runs on the model of one of your
 agents, can't see your systems, and creates nothing until you click.
 
+Or skip the interview: **Templates** (`/templates`, linked from the
+sidebar and the Agents page) are ready-made agents: answer customer
+emails, refund approvals, triage incidents, check expense claims, lead
+follow-up, inbox to tasks, and a weekly research digest. Preview one's instructions and setup checklist, then create it
+the same way, as many times as you like. Templates live in
+`core/system-agents/templates.ts`, in the same shape the interview
+suggests.
+
 Every notification links to a **decision page**: a signed, single-use
 link (`/decide/<token>`, valid 7 days) where whoever got the message can
 approve, deny, edit the arguments or answer a question, with no login and
@@ -240,8 +250,10 @@ under the hood.
 ## Scheduled tasks
 
 The server runs one scheduler (`core/scheduler.ts`) that sends a message
-to an agent later — once (`run_at`) or on an interval (`every: "1h"`) —
-from the console's **Schedules** tab, the `GET/POST
+to an agent later — once (`run_at`) or on an interval (`every: "1h"`),
+optionally from a set first run (`start_at`), which every later run keeps:
+`every: "1d"` from a 9:00 start runs daily at 9:00, `every: "7d"` from a
+Monday runs on Mondays — from the console's **Schedules** tab, the `GET/POST
 /agents/<name>/schedules` API, or the agent itself: every agent has
 built-in `system_schedule_task`, `system_list_scheduled_tasks`,
 `system_check_scheduled_task` and `system_cancel_scheduled_task` tools,

package/dist/bin/cli.js

@@ -37,9 +37,10 @@ const MODEL_ENV_VAR = {
 // literal in generated code — an operator-supplied systemPrompt (from
 // the admin UI's Create new agent form, say) containing a literal quote
 // or backslash would otherwise produce invalid, or silently different,
-// generated TypeScript.
+// generated TypeScript. Line breaks too: a multi-line prompt (from a
+// template or the interview) would otherwise end the literal mid-line.
 function tsStringLiteral(value) {
-    return "'" + value.replace(/\\/g, '\\\\').replace(/'/g, "\\'") + "'";
+    return "'" + value.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\r/g, '\\r').replace(/\n/g, '\\n') + "'";
 }
 /** 'loopengine' for a real consumer project — the only thing that ever
  * resolves once this package is genuinely installed as a dependency. A

package/dist/core/agent-config.d.ts

@@ -91,7 +91,14 @@ export type ApprovalOnlyHttpNotifierEvent = 'approval';
  * see `core/http-notify-triggers/email.ts`'s own doc comment for why
  * (an SMTP client/provider SDK is a dependency this package deliberately
  * doesn't carry). */
-export type SendEmail = (to: string, subject: string, html: string) => Promise<void>;
+export type SendEmail = (to: string, subject: string, html: string, meta?: SendEmailMeta) => Promise<void>;
+/** What an email is about, passed as `SendEmail`'s optional 4th argument
+ * so a sender can log it (core/email-senders.ts records deliveries with
+ * it). A sender that doesn't care can ignore it. */
+export interface SendEmailMeta {
+    kind: 'approval' | 'question' | 'run_start' | 'run_finish' | 'test';
+    pendingId?: string;
+}
 /** One row `channel: 'database'` (`core/http-notify-triggers/database.ts`)
  * inserts per pending approval — implement `insert()` against whatever
  * real database/ORM you already have (a single INSERT, a Prisma/Drizzle
@@ -159,9 +166,13 @@ export interface PendingApprovalsRepository {
  *     `http-notify-triggers/lark.ts`'s `LarkNotifier` (lower
  *     confidence on exact card-schema field names — see that file's own
  *     header comment).
- *   - `'email'` — a `sendEmail` callback plus a signed, expiring
- *     magic-link token per approval/question, via
- *     `http-notify-triggers/email.ts`'s `EmailNotifier`.
+ *   - `'email'` — a `sendEmail` callback, via
+ *     `http-notify-triggers/email.ts`'s `EmailNotifier`. With
+ *     `resolveBaseUrl`/`answerBaseUrl`/`signingSecret`, each email carries
+ *     its own signed magic links to *your* endpoints; without them, it
+ *     links to this server's own decision page (`/decide/<token>`, at
+ *     `publicUrl`), the same page Slack and Lark messages link to — what
+ *     the console's Messaging tab sets up.
  *   - `'database'`/`'redis'` — not a notification channel at all (see
  *     `ApprovalOnlyHttpNotifierEvent`'s own doc comment): a row insert or
  *     a queue push for a separate worker/dashboard to poll, via
@@ -213,10 +224,11 @@ export type HttpNotifierConfig = {
     config: {
         to: string;
         sendEmail: SendEmail;
-        resolveBaseUrl: string;
-        answerBaseUrl: string;
-        signingSecret: string;
+        resolveBaseUrl?: string;
+        answerBaseUrl?: string;
+        signingSecret?: string;
         linkTtlMs?: number;
+        publicUrl?: string;
     };
     events: HttpNotifierEvent[];
 } | {

package/dist/core/email-senders.d.ts

@@ -0,0 +1,26 @@
+import type { SendEmail } from '#core/agent-config.js';
+export type EmailProvider = 'resend' | 'sendgrid' | 'postmark';
+export declare const EMAIL_PROVIDERS: EmailProvider[];
+/** "Ops <ops@example.com>" or "ops@example.com". */
+export declare function parseAddress(value: string): {
+    name?: string;
+    email: string;
+} | undefined;
+/** A comma- or semicolon-separated list of addresses; undefined when any
+ * of them isn't a valid address. */
+export declare function parseRecipients(value: string): string[] | undefined;
+/** A plain-text version of the HTML body, for mail clients (and spam
+ * filters) that prefer one. */
+export declare function htmlToText(html: string): string;
+export interface ProviderSenderOptions {
+    provider: EmailProvider;
+    apiKey: string;
+    /** The sender, e.g. "LoopEngine <approvals@example.com>"; the provider
+     * must allow sending from its domain. */
+    from: string;
+    /** For the deliveries list. */
+    agent: string;
+}
+/** A SendEmail that sends through `provider`. Throws when the provider
+ * refuses the email, after recording the failure. */
+export declare function createProviderSendEmail(options: ProviderSenderOptions): SendEmail;

package/dist/core/email-senders.js

@@ -0,0 +1,108 @@
+import { recordDelivery } from '#core/notifier-deliveries.js';
+export const EMAIL_PROVIDERS = ['resend', 'sendgrid', 'postmark'];
+const ENDPOINTS = {
+    resend: 'https://api.resend.com/emails',
+    sendgrid: 'https://api.sendgrid.com/v3/mail/send',
+    postmark: 'https://api.postmarkapp.com/email',
+};
+const ADDRESS = /^[^\s@<>,"]+@[^\s@<>,"]+\.[^\s@<>,"]+$/;
+/** "Ops <ops@example.com>" or "ops@example.com". */
+export function parseAddress(value) {
+    const trimmed = value.trim();
+    const named = /^(.*?)\s*<([^<>]+)>$/.exec(trimmed);
+    const email = (named ? named[2] : trimmed).trim();
+    if (!ADDRESS.test(email))
+        return undefined;
+    const name = named?.[1].replace(/^"|"$/g, '').trim();
+    return name ? { name, email } : { email };
+}
+/** A comma- or semicolon-separated list of addresses; undefined when any
+ * of them isn't a valid address. */
+export function parseRecipients(value) {
+    const parts = value.split(/[,;]/).map((p) => p.trim()).filter(Boolean);
+    if (!parts.length || parts.some((p) => !parseAddress(p)))
+        return undefined;
+    return parts;
+}
+/** A plain-text version of the HTML body, for mail clients (and spam
+ * filters) that prefer one. */
+export function htmlToText(html) {
+    return html
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<\/(p|div|li|tr|h[1-6])>/gi, '\n')
+        .replace(/<a [^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, '$2 ($1)')
+        .replace(/<[^>]+>/g, '')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, '&')
+        .replace(/[ \t]+\n/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+function requestFor(provider, apiKey, from, to, subject, html) {
+    const text = htmlToText(html);
+    switch (provider) {
+        case 'resend':
+            return {
+                method: 'POST',
+                headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+                body: JSON.stringify({ from, to, subject, html, text }),
+            };
+        case 'sendgrid': {
+            const sender = parseAddress(from);
+            return {
+                method: 'POST',
+                headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    personalizations: [{ to: to.map((t) => parseAddress(t)) }],
+                    from: sender,
+                    subject,
+                    content: [
+                        { type: 'text/plain', value: text },
+                        { type: 'text/html', value: html },
+                    ],
+                }),
+            };
+        }
+        case 'postmark':
+            return {
+                method: 'POST',
+                headers: { 'x-postmark-server-token': apiKey, 'content-type': 'application/json', accept: 'application/json' },
+                body: JSON.stringify({ From: from, To: to.join(', '), Subject: subject, HtmlBody: html, TextBody: text, MessageStream: 'outbound' }),
+            };
+    }
+}
+/** The provider's own error message, when its response carries one. */
+async function errorDetail(res) {
+    const body = (await res.json().catch(() => undefined));
+    return body?.message ?? body?.Message ?? body?.errors?.[0]?.message ?? body?.name ?? '';
+}
+/** A SendEmail that sends through `provider`. Throws when the provider
+ * refuses the email, after recording the failure. */
+export function createProviderSendEmail(options) {
+    return async (to, subject, html, meta) => {
+        const recipients = parseRecipients(to);
+        if (!recipients)
+            throw new Error(`"${to}" isn't a valid list of email addresses`);
+        const delivery = { agent: options.agent, kind: meta?.kind ?? 'approval', url: `${options.provider}:${recipients.join(',')}`, attempt: 1, ...(meta?.pendingId ? { pendingId: meta.pendingId } : {}) };
+        let res;
+        try {
+            res = await fetch(ENDPOINTS[options.provider], requestFor(options.provider, options.apiKey, options.from, recipients, subject, html));
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            recordDelivery({ at: new Date().toISOString(), ...delivery, ok: false, error });
+            throw new Error(`${options.provider} couldn't be reached: ${error}`);
+        }
+        if (!res.ok) {
+            const detail = await errorDetail(res);
+            const error = `HTTP ${res.status}${detail ? `: ${detail}` : ''}`;
+            recordDelivery({ at: new Date().toISOString(), ...delivery, ok: false, status: res.status, error });
+            throw new Error(`${options.provider} refused the email (${error})`);
+        }
+        recordDelivery({ at: new Date().toISOString(), ...delivery, ok: true, status: res.status });
+    };
+}

package/dist/core/http-notifier.js

@@ -48,7 +48,7 @@ export function describeNotifier(config) {
     }
     if (!file)
         return { source: 'none' };
-    const { missingSecret } = notifierConfigFromFile(file, createAgentEnv(config.name, dir));
+    const { missingSecret } = notifierConfigFromFile(file, createAgentEnv(config.name, dir), config.name);
     return { source: missingSecret ? 'none' : 'file', channel: file.channel, events: file.events, file, missingSecret };
 }
 /** AgentConfig.httpNotifier when the agent sets one in code; otherwise
@@ -77,7 +77,7 @@ function resolveFromFile(config) {
     }
     if (!file)
         return EMPTY;
-    const { config: httpNotifier } = notifierConfigFromFile(file, createAgentEnv(config.name, dir));
+    const { config: httpNotifier } = notifierConfigFromFile(file, createAgentEnv(config.name, dir), config.name);
     return httpNotifier ? buildResolved(httpNotifier, dir) : EMPTY;
 }
 /** `agentDir`: where a Slack request's thread is recorded, so replies in
@@ -129,16 +129,16 @@ function buildResolved(httpNotifier, agentDir) {
             break;
         }
         case 'email': {
-            const { to, sendEmail, resolveBaseUrl, answerBaseUrl, signingSecret, linkTtlMs } = httpNotifier.config;
-            const email = new EmailNotifier({ to, sendEmail, resolveBaseUrl, answerBaseUrl, signingSecret, linkTtlMs });
+            const { to, sendEmail, resolveBaseUrl, answerBaseUrl, signingSecret, linkTtlMs, publicUrl } = httpNotifier.config;
+            const email = new EmailNotifier({ to, sendEmail, resolveBaseUrl, answerBaseUrl, signingSecret, linkTtlMs, publicUrl });
             resolved = {
                 approver: events.has('approval') ? email : undefined,
                 questionHandler: events.has('question') ? email : undefined,
                 onRunStart: events.has('run_start')
-                    ? (context) => email.sendAnnouncement(formatEmailLifecycleSubject('run_start', context), formatChatLifecycleMessage('run_start', context))
+                    ? (context) => email.sendAnnouncement(formatEmailLifecycleSubject('run_start', context), formatChatLifecycleMessage('run_start', context), 'run_start')
                     : undefined,
                 onRunFinish: events.has('run_finish')
-                    ? (context) => email.sendAnnouncement(formatEmailLifecycleSubject('run_finish', context), formatChatLifecycleMessage('run_finish', context))
+                    ? (context) => email.sendAnnouncement(formatEmailLifecycleSubject('run_finish', context), formatChatLifecycleMessage('run_finish', context), 'run_finish')
                     : undefined,
             };
             break;

package/dist/core/http-notify-triggers/email.d.ts

@@ -19,18 +19,24 @@ export declare function verifyMagicLink(token: string, signingSecret: string): E
 export declare class EmailNotifier implements DurableApprover, DurableQuestionHandler {
     private readonly to;
     private readonly sendEmail;
-    private readonly resolveBaseUrl;
-    private readonly answerBaseUrl;
-    private readonly signingSecret;
+    /** Magic-link mode: links to YOUR endpoints, signed with signingSecret. */
+    private readonly magic?;
+    /** Decision-page mode: where this server is reachable. */
+    private readonly publicUrl?;
     private readonly linkTtlMs;
     constructor(options: {
         to: string;
         sendEmail: SendEmail;
-        resolveBaseUrl: string;
-        answerBaseUrl: string;
-        signingSecret: string;
+        resolveBaseUrl?: string;
+        answerBaseUrl?: string;
+        signingSecret?: string;
         linkTtlMs?: number;
+        publicUrl?: string;
     });
+    private expiryNote;
+    /** Decision-page mode: one link to decide (or answer) on this server,
+     * or where to find the request when the server's address isn't known. */
+    private decideHtml;
     requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string): {
         pendingId: string;
     };
@@ -39,6 +45,6 @@ export declare class EmailNotifier implements DurableApprover, DurableQuestionHa
     };
     /** Public: core/http-notifier.ts's own onRunStart/onRunFinish lifecycle
      * sender for `channel: 'email'` calls this directly — a plain
-     * announcement, no magic link, since there's nothing to resolve. */
-    sendAnnouncement(subject: string, text: string): void;
+     * announcement, no link, since there's nothing to resolve. */
+    sendAnnouncement(subject: string, text: string, kind?: 'run_start' | 'run_finish' | 'test'): void;
 }

package/dist/core/http-notify-triggers/email.js

@@ -31,7 +31,15 @@
 // file builds one: a small HMAC-signed, expiring token embedded in the
 // link itself, verified before ever touching loopengine's own
 // resolve/answer routes.
+//
+// Without resolveBaseUrl/answerBaseUrl/signingSecret it needs none of
+// that: each email links to this server's own decision page
+// (core/approval-links.ts, /decide/<token>), the same page Slack and Lark
+// messages link to, where the person approves, denies, edits or answers.
+// That's what an email channel set from the console's Messaging tab uses.
 import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { decidePath, decisionLinkTtlMs } from '../approval-links.js';
+import { publicBaseUrl } from './webhook.js';
 function signMagicLink(payload, expiresInMs, signingSecret) {
     const body = Buffer.from(JSON.stringify({ ...payload, exp: Date.now() + expiresInMs })).toString('base64url');
     const signature = createHmac('sha256', signingSecret).update(body).digest('base64url');
@@ -67,22 +75,51 @@ function escapeHtml(s) {
 export class EmailNotifier {
     to;
     sendEmail;
-    resolveBaseUrl; // e.g. https://yourapp.com/email/approvals — YOUR route, not loopengine's own address
-    answerBaseUrl; // e.g. https://yourapp.com/email/questions — YOUR route, not loopengine's own address
-    signingSecret;
+    /** Magic-link mode: links to YOUR endpoints, signed with signingSecret. */
+    magic;
+    /** Decision-page mode: where this server is reachable. */
+    publicUrl;
     linkTtlMs;
     constructor(options) {
         this.to = options.to;
         this.sendEmail = options.sendEmail;
-        this.resolveBaseUrl = options.resolveBaseUrl;
-        this.answerBaseUrl = options.answerBaseUrl;
-        this.signingSecret = options.signingSecret;
-        this.linkTtlMs = options.linkTtlMs ?? 3 * 24 * 60 * 60_000; // 3 days — long enough for someone to actually check email, short enough that a leaked link doesn't stay live forever
+        const { resolveBaseUrl, answerBaseUrl, signingSecret } = options;
+        const given = [resolveBaseUrl, answerBaseUrl, signingSecret].filter(Boolean).length;
+        if (given > 0 && given < 3) {
+            throw new Error('EmailNotifier: give resolveBaseUrl, answerBaseUrl and signingSecret together (magic links), or none of them (decision-page links)');
+        }
+        if (resolveBaseUrl && answerBaseUrl && signingSecret)
+            this.magic = { resolveBaseUrl, answerBaseUrl, signingSecret };
+        this.publicUrl = options.publicUrl;
+        // Magic links: 3 days — long enough for someone to actually check
+        // email, short enough that a leaked link doesn't stay live forever.
+        // Decision-page links last as long as the decision page allows.
+        this.linkTtlMs = options.linkTtlMs ?? (this.magic ? 3 * 24 * 60 * 60_000 : decisionLinkTtlMs());
+    }
+    expiryNote() {
+        const hours = Math.round(this.linkTtlMs / 3_600_000);
+        return `<p style="color:#888;font-size:12px">This link expires in ${hours >= 48 ? `${Math.round(hours / 24)} days` : `${hours} hours`}.</p>`;
+    }
+    /** Decision-page mode: one link to decide (or answer) on this server,
+     * or where to find the request when the server's address isn't known. */
+    decideHtml(pendingId, kind) {
+        const base = publicBaseUrl(this.publicUrl);
+        if (!base)
+            return `<p>Open this agent's Messaging tab in the LoopEngine console to ${kind === 'approval' ? 'approve or deny it' : 'answer'}.</p>`;
+        return `<p><a href="${base}${decidePath(pendingId, kind)}">${kind === 'approval' ? 'Review and approve or deny' : 'Answer'}</a></p>` + this.expiryNote();
     }
     requestDurableApproval(tool, args, scope, reason) {
         const pendingId = randomUUID();
-        const approveLink = `${this.resolveBaseUrl}?token=${signMagicLink({ pendingId, decision: 'approve' }, this.linkTtlMs, this.signingSecret)}`;
-        const denyLink = `${this.resolveBaseUrl}?token=${signMagicLink({ pendingId, decision: 'deny' }, this.linkTtlMs, this.signingSecret)}`;
+        let links;
+        if (this.magic) {
+            const { resolveBaseUrl, signingSecret } = this.magic;
+            const approveLink = `${resolveBaseUrl}?token=${signMagicLink({ pendingId, decision: 'approve' }, this.linkTtlMs, signingSecret)}`;
+            const denyLink = `${resolveBaseUrl}?token=${signMagicLink({ pendingId, decision: 'deny' }, this.linkTtlMs, signingSecret)}`;
+            links = `<p><a href="${approveLink}">Approve</a> &nbsp;|&nbsp; <a href="${denyLink}">Deny</a></p>` + this.expiryNote();
+        }
+        else {
+            links = this.decideHtml(pendingId, 'approval');
+        }
         // Not awaited — requestDurableApproval returns immediately, by
         // contract (see DurableApprover's own doc comment). Logged instead of
         // thrown on failure.
@@ -90,37 +127,42 @@ export class EmailNotifier {
             `<p><b>Args:</b> ${escapeHtml(JSON.stringify(args))}</p>` +
             `<p><b>Scope:</b> ${escapeHtml(`${scope.tenant}/${scope.environment}/${scope.agent}`)}</p>` +
             `<p><b>Reason:</b> ${escapeHtml(reason)}</p>` +
-            `<p><a href="${approveLink}">Approve</a> &nbsp;|&nbsp; <a href="${denyLink}">Deny</a></p>` +
-            `<p style="color:#888;font-size:12px">This link expires in ${Math.round(this.linkTtlMs / 3_600_000)} hours.</p>`).catch((err) => {
+            links, { kind: 'approval', pendingId }).catch((err) => {
             console.error(`[loopengine] EmailNotifier: sendEmail failed for pendingId '${pendingId}':`, err);
         });
         return { pendingId };
     }
     notifyPendingQuestion(question, options, agent, sessionId) {
         const pendingId = randomUUID();
-        const optionLinks = (options ?? [])
-            .map((option) => {
-            const token = signMagicLink({ pendingId, answer: option }, this.linkTtlMs, this.signingSecret);
-            return `<a href="${this.answerBaseUrl}?token=${token}">${escapeHtml(option)}</a>`;
-        })
-            .join(' &nbsp;|&nbsp; ');
-        const freeTextToken = signMagicLink({ pendingId }, this.linkTtlMs, this.signingSecret);
-        const freeTextLink = `${this.answerBaseUrl}?token=${freeTextToken}`;
-        this.sendEmail(this.to, `Question from ${agent}`, `<p>${escapeHtml(question)}</p>` +
-            (sessionId ? `<p style="color:#888;font-size:12px">Session: ${escapeHtml(sessionId)}</p>` : '') +
-            (optionLinks ? `<p>${optionLinks}</p>` : '') +
-            `<p><a href="${freeTextLink}">${optionLinks ? 'Or answer in your own words' : 'Answer'}</a></p>` +
-            `<p style="color:#888;font-size:12px">This link expires in ${Math.round(this.linkTtlMs / 3_600_000)} hours.</p>`).catch((err) => {
+        let links;
+        if (this.magic) {
+            const { answerBaseUrl, signingSecret } = this.magic;
+            const optionLinks = (options ?? [])
+                .map((option) => {
+                const token = signMagicLink({ pendingId, answer: option }, this.linkTtlMs, signingSecret);
+                return `<a href="${answerBaseUrl}?token=${token}">${escapeHtml(option)}</a>`;
+            })
+                .join(' &nbsp;|&nbsp; ');
+            const freeTextToken = signMagicLink({ pendingId }, this.linkTtlMs, signingSecret);
+            const freeTextLink = `${answerBaseUrl}?token=${freeTextToken}`;
+            links = (optionLinks ? `<p>${optionLinks}</p>` : '') + `<p><a href="${freeTextLink}">${optionLinks ? 'Or answer in your own words' : 'Answer'}</a></p>` + this.expiryNote();
+        }
+        else {
+            // The decision page offers the suggested answers itself.
+            const suggested = (options ?? []).length ? `<p>Suggested answers: ${(options ?? []).map(escapeHtml).join(', ')}</p>` : '';
+            links = suggested + this.decideHtml(pendingId, 'question');
+        }
+        this.sendEmail(this.to, `Question from ${agent}`, `<p>${escapeHtml(question)}</p>` + (sessionId ? `<p style="color:#888;font-size:12px">Session: ${escapeHtml(sessionId)}</p>` : '') + links, { kind: 'question', pendingId }).catch((err) => {
             console.error(`[loopengine] EmailNotifier: sendEmail failed for pendingId '${pendingId}':`, err);
         });
         return { pendingId };
     }
     /** Public: core/http-notifier.ts's own onRunStart/onRunFinish lifecycle
      * sender for `channel: 'email'` calls this directly — a plain
-     * announcement, no magic link, since there's nothing to resolve. */
-    sendAnnouncement(subject, text) {
-        this.sendEmail(this.to, subject, `<p>${escapeHtml(text)}</p>`).catch((err) => {
-            console.error('[loopengine] EmailNotifier: sendEmail failed for lifecycle announcement:', err);
+     * announcement, no link, since there's nothing to resolve. */
+    sendAnnouncement(subject, text, kind = 'run_finish') {
+        this.sendEmail(this.to, subject, `<p>${escapeHtml(text)}</p>`, { kind }).catch((err) => {
+            console.error('[loopengine] EmailNotifier: sendEmail failed for an announcement:', err);
         });
     }
 }

package/dist/core/notifier-file.d.ts

@@ -1,5 +1,6 @@
 import type { AgentEnv, HttpNotifierConfig, HttpNotifierEvent } from '#core/agent-config.js';
-export type NotifierFileChannel = 'webhook' | 'slack' | 'lark';
+import { type EmailProvider } from '#core/email-senders.js';
+export type NotifierFileChannel = 'webhook' | 'slack' | 'lark' | 'email';
 export interface NotifierFile {
     channel: NotifierFileChannel;
     events: HttpNotifierEvent[];
@@ -10,6 +11,12 @@ export interface NotifierFile {
     /** lark: app id and chat to post into. */
     appId?: string;
     chatId?: string;
+    /** email: who receives requests (comma-separated), who they come from
+     * ("LoopEngine <approvals@example.com>"), and the provider that sends
+     * them. */
+    to?: string;
+    from?: string;
+    provider?: EmailProvider;
     /** Where this server is reachable, for the links in each message —
      * remembered from the console's own address when saving.
      * LOOPENGINE_PUBLIC_URL, when set, wins over it. */
@@ -48,8 +55,9 @@ export declare function writeNotifierFile(dir: string, input: unknown): Notifier
 export declare function removeNotifierFile(dir: string): void;
 /** The HttpNotifierConfig a connection describes, with its secret read
  * from `env` — or which secret is missing, so nothing is sent unsigned
- * or unauthenticated. */
-export declare function notifierConfigFromFile(file: NotifierFile, env: AgentEnv): {
+ * or unauthenticated. `agentName` labels email deliveries in the
+ * console's list. */
+export declare function notifierConfigFromFile(file: NotifierFile, env: AgentEnv, agentName?: string): {
     config?: HttpNotifierConfig;
     missingSecret?: string;
 };

package/dist/core/notifier-file.js

@@ -18,24 +18,26 @@
 // messaging.yml.
 //
 // The file holds only non-secret settings. The one secret each channel
-// needs (a webhook signing secret, a Slack bot token, a Lark app secret)
+// needs (a webhook signing secret, a Slack bot token, a Lark app secret, an email provider's API key)
 // lives in the agent's own env (agents/<name>/.env by default, through
 // core/secret-store.ts) under a fixed name, so it's never written into a
 // file that might get committed.
 import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { EMAIL_PROVIDERS, createProviderSendEmail, parseAddress, parseRecipients } from '#core/email-senders.js';
 /** The env var each channel's secret is read from, per agent. */
 export const NOTIFIER_SECRET_VARS = {
     webhook: 'LOOPENGINE_NOTIFIER_WEBHOOK_SECRET',
     slack: 'LOOPENGINE_NOTIFIER_SLACK_BOT_TOKEN',
     lark: 'LOOPENGINE_NOTIFIER_LARK_APP_SECRET',
+    email: 'LOOPENGINE_NOTIFIER_EMAIL_API_KEY',
 };
 /** Optional: a Slack app's signing secret, per agent. Set, it turns on
  * Approve/Deny buttons in Slack, handled by the server itself at
  * POST /hooks/slack/<agent>; unset, messages carry only the decision link. */
 export const NOTIFIER_SLACK_SIGNING_SECRET_VAR = 'LOOPENGINE_NOTIFIER_SLACK_SIGNING_SECRET';
-const CHANNELS = ['webhook', 'slack', 'lark'];
+const CHANNELS = ['webhook', 'slack', 'lark', 'email'];
 const EVENTS = ['approval', 'question', 'run_start', 'run_finish'];
 export class NotifierFileError extends Error {
 }
@@ -99,7 +101,7 @@ export function validateNotifierFile(input) {
             throw new NotifierFileError('channelId is required for slack');
         file.channelId = channelId;
     }
-    else {
+    else if (channel === 'lark') {
         const appId = str('appId');
         const chatId = str('chatId');
         if (!appId || !chatId)
@@ -107,6 +109,21 @@ export function validateNotifierFile(input) {
         file.appId = appId;
         file.chatId = chatId;
     }
+    else {
+        const to = str('to');
+        const recipients = to ? parseRecipients(to) : undefined;
+        if (!recipients)
+            throw new NotifierFileError('to must be one or more email addresses, separated by commas');
+        const from = str('from');
+        if (!from || !parseAddress(from))
+            throw new NotifierFileError('from must be an email address, like "LoopEngine <approvals@example.com>"');
+        const provider = str('provider');
+        if (!provider || !EMAIL_PROVIDERS.includes(provider))
+            throw new NotifierFileError(`provider must be one of: ${EMAIL_PROVIDERS.join(', ')}`);
+        file.to = recipients.join(', ');
+        file.from = from;
+        file.provider = provider;
+    }
     return file;
 }
 /** The agent's connection: messaging.yml's first, else the older
@@ -147,8 +164,9 @@ export function removeNotifierFile(dir) {
 }
 /** The HttpNotifierConfig a connection describes, with its secret read
  * from `env` — or which secret is missing, so nothing is sent unsigned
- * or unauthenticated. */
-export function notifierConfigFromFile(file, env) {
+ * or unauthenticated. `agentName` labels email deliveries in the
+ * console's list. */
+export function notifierConfigFromFile(file, env, agentName = '') {
     const secretVar = NOTIFIER_SECRET_VARS[file.channel];
     const secret = env.get(secretVar);
     if (!secret)
@@ -178,5 +196,19 @@ export function notifierConfigFromFile(file, env) {
             // No card buttons: nothing built in handles Lark's card callbacks yet,
             // so a console-configured Lark notifier relies on the decision link.
             return { config: { channel: 'lark', config: { appId: file.appId, appSecret: secret, chatId: file.chatId, publicUrl: file.publicUrl, buttons: false }, events: file.events } };
+        case 'email':
+            // Links to the decision page, like Lark without buttons; the secret
+            // is the provider's API key.
+            return {
+                config: {
+                    channel: 'email',
+                    config: {
+                        to: file.to,
+                        sendEmail: createProviderSendEmail({ provider: file.provider, apiKey: secret, from: file.from, agent: agentName }),
+                        publicUrl: file.publicUrl,
+                    },
+                    events: file.events,
+                },
+            };
     }
 }

package/dist/core/scheduler.d.ts

@@ -73,9 +73,15 @@ export declare function setSchedulerStore(next: SchedulerStore): void;
 export interface CreateScheduledTaskInput {
     agent: string;
     message: string;
+    /** `start_at` (with `every` only): when the first run is, and so the
+     * time of day / day of week every later run keeps, e.g. every "1d"
+     * from "2026-11-02T09:00:00+08:00" runs daily at 9:00. A start in the
+     * past is fine: the first run is its next slot after now. Without it,
+     * the first run is one interval from now. */
     schedule: {
         run_at?: unknown;
         every?: unknown;
+        start_at?: unknown;
     };
     task_name?: string;
     notify?: boolean;