aiden-runtime 4.1.5 → 4.6.0

package/dist/core/v4/daemon/triggerBus.js

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/triggerBus.ts — v4.5 Phase 1: durable trigger bus.
+ *
+ * The CENTRAL persistence layer for the daemon. Every accepted
+ * trigger (file watcher fire, webhook delivery, email match,
+ * scheduled job tick) normalizes into a `trigger_events` row
+ * BEFORE returning 202 Accepted / marking the email seen /
+ * enqueuing schedule. ONE durable queue, not 4 parallel half-
+ * baked persistence layers.
+ *
+ * Concurrency semantics:
+ *   - `insert()` uses INSERT OR IGNORE against the partial unique
+ *     index on (source, idempotency_key). Duplicates return the
+ *     existing id with `inserted: false`.
+ *   - `claim()` atomically picks the oldest pending event and
+ *     sets status='claimed' + claim_owner + claim_expires_at. A
+ *     per-claim nonce (claimToken) is returned; subsequent
+ *     release/markDone/markFailed validate it to prevent double-
+ *     completion races across sibling daemons.
+ *   - `reclaimExpired()` returns to 'pending' any claimed row
+ *     whose lease has elapsed (called by the daemon ticker every
+ *     30s + on boot).
+ *   - `markFailed()` increments attempts; on attempts >=
+ *     maxAttempts the row moves to 'dead_letter' instead of
+ *     returning to pending.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_ATTEMPTS = exports.DEFAULT_CLAIM_LEASE_MS = void 0;
+exports.createTriggerBus = createTriggerBus;
+const node_crypto_1 = require("node:crypto");
+exports.DEFAULT_CLAIM_LEASE_MS = 5 * 60000;
+exports.DEFAULT_MAX_ATTEMPTS = 3;
+function rowToTs(r) {
+    return {
+        id: r.id,
+        source: r.source,
+        sourceKey: r.source_key,
+        idempotencyKey: r.idempotency_key,
+        payload: safeJsonParse(r.payload_json),
+        status: r.status,
+        attempts: r.attempts,
+        claimOwner: r.claim_owner,
+        claimExpiresAt: r.claim_expires_at,
+        lastError: r.last_error,
+        createdAt: r.created_at,
+        updatedAt: r.updated_at,
+        completedAt: r.completed_at,
+        runId: r.run_id,
+    };
+}
+function safeJsonParse(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return {};
+    }
+}
+function createTriggerBus(opts) {
+    const db = opts.db;
+    // In-memory map of valid claim tokens. Stored separately from
+    // SQLite so cross-daemon claim attempts can't forge a token by
+    // reading the row. Token is wiped on markDone/release/markFailed.
+    const activeClaims = new Map();
+    return {
+        insert(ev) {
+            const now = Date.now();
+            const payloadJson = JSON.stringify(ev.payload ?? {});
+            const result = db
+                .prepare(`INSERT OR IGNORE INTO trigger_events
+             (source, source_key, idempotency_key, payload_json,
+              status, attempts, created_at, updated_at)
+           VALUES (?, ?, ?, ?, 'pending', 0, ?, ?)`)
+                .run(ev.source, ev.sourceKey, ev.idempotencyKey ?? null, payloadJson, now, now);
+            if (result.changes > 0) {
+                return { id: Number(result.lastInsertRowid), inserted: true };
+            }
+            // Dedup hit — return the existing id.
+            const existing = db
+                .prepare('SELECT id FROM trigger_events WHERE source = ? AND idempotency_key = ?')
+                .get(ev.source, ev.idempotencyKey ?? null);
+            if (!existing) {
+                // Defensive — shouldn't happen unless idempotency_key was null,
+                // in which case INSERT OR IGNORE wouldn't have skipped.
+                throw new Error('triggerBus.insert: INSERT OR IGNORE produced no row but no existing match found');
+            }
+            return { id: existing.id, inserted: false };
+        },
+        claim(opts2 = { ownerId: '' }) {
+            const leaseMs = opts2.leaseMs ?? exports.DEFAULT_CLAIM_LEASE_MS;
+            const now = Date.now();
+            const expires = now + leaseMs;
+            const claimToken = (0, node_crypto_1.randomUUID)();
+            const tx = db.transaction(() => {
+                // Pick the oldest pending event matching the optional source filter.
+                // v4.5 Phase 7 — honour cooldown: skip pending rows whose
+                // claim_expires_at is still in the future (re-set by
+                // markFailed with cooldownMs to delay re-claim).
+                const sql = opts2.source
+                    ? `SELECT id FROM trigger_events
+              WHERE status = 'pending' AND source = ?
+                AND (claim_expires_at IS NULL OR claim_expires_at <= ?)
+              ORDER BY created_at LIMIT 1`
+                    : `SELECT id FROM trigger_events
+              WHERE status = 'pending'
+                AND (claim_expires_at IS NULL OR claim_expires_at <= ?)
+              ORDER BY created_at LIMIT 1`;
+                const candidate = (opts2.source
+                    ? db.prepare(sql).get(opts2.source, now)
+                    : db.prepare(sql).get(now));
+                if (!candidate)
+                    return null;
+                const upd = db
+                    .prepare(`UPDATE trigger_events
+                SET status           = 'claimed',
+                    claim_owner      = ?,
+                    claim_expires_at = ?,
+                    updated_at       = ?,
+                    attempts         = attempts + 1
+              WHERE id = ? AND status = 'pending'`)
+                    .run(opts2.ownerId, expires, now, candidate.id);
+                if (upd.changes === 0)
+                    return null; // race lost
+                const row = db
+                    .prepare('SELECT * FROM trigger_events WHERE id = ?')
+                    .get(candidate.id);
+                return rowToTs(row);
+            });
+            const row = tx();
+            if (!row)
+                return null;
+            activeClaims.set(row.id, claimToken);
+            return { ...row, claimToken };
+        },
+        renewClaim(eventId, claimToken, extendMs) {
+            if (activeClaims.get(eventId) !== claimToken)
+                return false;
+            const now = Date.now();
+            const upd = db
+                .prepare(`UPDATE trigger_events
+              SET claim_expires_at = ?,
+                  updated_at       = ?
+            WHERE id = ? AND status = 'claimed'`)
+                .run(now + extendMs, now, eventId);
+            return upd.changes > 0;
+        },
+        release(eventId, claimToken) {
+            if (activeClaims.get(eventId) !== claimToken)
+                return;
+            const now = Date.now();
+            db.prepare(`UPDATE trigger_events
+            SET status           = 'pending',
+                claim_owner      = NULL,
+                claim_expires_at = NULL,
+                updated_at       = ?
+          WHERE id = ? AND status = 'claimed'`).run(now, eventId);
+            activeClaims.delete(eventId);
+        },
+        markDone(eventId, claimToken, runId) {
+            if (activeClaims.get(eventId) !== claimToken)
+                return;
+            const now = Date.now();
+            db.prepare(`UPDATE trigger_events
+            SET status           = 'done',
+                claim_owner      = NULL,
+                claim_expires_at = NULL,
+                updated_at       = ?,
+                completed_at     = ?,
+                run_id           = COALESCE(?, run_id)
+          WHERE id = ? AND status = 'claimed'`).run(now, now, runId ?? null, eventId);
+            activeClaims.delete(eventId);
+        },
+        markFailed(eventId, claimToken, error, opts2 = {}) {
+            if (activeClaims.get(eventId) !== claimToken)
+                return;
+            const max = opts2.maxAttempts ?? exports.DEFAULT_MAX_ATTEMPTS;
+            const now = Date.now();
+            const truncated = error.length > 1024 ? error.slice(0, 1024) + '…' : error;
+            // v4.5 Phase 7 — optional cooldown delays re-claim. When set,
+            // we stash `now + cooldownMs` in `claim_expires_at` while
+            // status='pending'. The claim picker filters out pending rows
+            // whose claim_expires_at is in the future (added below). Bus
+            // poll loop will pick the row up naturally once cooldown
+            // elapses — no explicit sleep needed.
+            const cooldownUntil = opts2.cooldownMs && opts2.cooldownMs > 0
+                ? now + opts2.cooldownMs
+                : null;
+            const tx = db.transaction(() => {
+                const row = db
+                    .prepare('SELECT attempts FROM trigger_events WHERE id = ?')
+                    .get(eventId);
+                if (!row)
+                    return;
+                // attempts was already incremented at claim time. Move to
+                // dead_letter when the count hits max, else return to pending.
+                if (row.attempts >= max) {
+                    db.prepare(`UPDATE trigger_events
+                SET status           = 'dead_letter',
+                    claim_owner      = NULL,
+                    claim_expires_at = NULL,
+                    last_error       = ?,
+                    updated_at       = ?,
+                    completed_at     = ?
+              WHERE id = ?`).run(truncated, now, now, eventId);
+                }
+                else {
+                    db.prepare(`UPDATE trigger_events
+                SET status           = 'pending',
+                    claim_owner      = NULL,
+                    claim_expires_at = ?,
+                    last_error       = ?,
+                    updated_at       = ?
+              WHERE id = ?`).run(cooldownUntil, truncated, now, eventId);
+                }
+            });
+            tx();
+            activeClaims.delete(eventId);
+        },
+        reclaimExpired(now) {
+            const cutoff = now ?? Date.now();
+            const upd = db
+                .prepare(`UPDATE trigger_events
+              SET status           = 'pending',
+                  claim_owner      = NULL,
+                  claim_expires_at = NULL,
+                  last_error       = COALESCE(last_error, 'claim lease expired'),
+                  updated_at       = ?
+            WHERE status = 'claimed'
+              AND claim_expires_at IS NOT NULL
+              AND claim_expires_at < ?`)
+                .run(cutoff, cutoff);
+            return { reclaimed: upd.changes };
+        },
+        deadLetter(eventId, reason) {
+            const now = Date.now();
+            db.prepare(`UPDATE trigger_events
+            SET status           = 'dead_letter',
+                claim_owner      = NULL,
+                claim_expires_at = NULL,
+                last_error       = ?,
+                updated_at       = ?,
+                completed_at     = ?
+          WHERE id = ?`).run(reason.length > 1024 ? reason.slice(0, 1024) + '…' : reason, now, now, eventId);
+            activeClaims.delete(eventId);
+        },
+        stats() {
+            const counts = db
+                .prepare(`SELECT status, COUNT(*) AS c FROM trigger_events GROUP BY status`)
+                .all();
+            const m = {};
+            for (const r of counts)
+                m[r.status] = r.c;
+            const oldest = db
+                .prepare(`SELECT MIN(created_at) AS t FROM trigger_events WHERE status = 'pending'`)
+                .get();
+            const oldestPendingMs = oldest.t != null ? Date.now() - oldest.t : null;
+            return {
+                pending: m.pending ?? 0,
+                claimed: m.claimed ?? 0,
+                running: m.running ?? 0,
+                deadLetter: m.dead_letter ?? 0,
+                oldestPendingMs,
+            };
+        },
+        get(eventId) {
+            const r = db
+                .prepare('SELECT * FROM trigger_events WHERE id = ?')
+                .get(eventId);
+            return r ? rowToTs(r) : null;
+        },
+    };
+}

package/dist/core/v4/daemon/triggers/email/allowlist.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/triggers/email/allowlist.ts — v4.5 Phase 4a.
+ *
+ * Compiles a per-trigger sender allowlist into a fast matcher.
+ * Glob syntax supported:
+ *   - Exact:    user@example.com
+ *   - Domain:   *@example.com
+ *   - Prefix:   alerts-*@example.com
+ *   - Both:     *-alerts-*@*.example.com
+ *
+ * Allowlist semantics:
+ *   - Default (empty list) = REJECT all. Trigger is functional only
+ *     after at least one --allow-sender is registered. This matches
+ *     the explicit-over-implicit security posture.
+ *   - Applied AFTER the automated-sender filter (we never trust
+ *     `noreply@<allowed-domain>`).
+ *   - Case-insensitive (RFC 5321: local-part is technically case-
+ *     sensitive, but in practice IS not).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileSenderAllowlist = compileSenderAllowlist;
+/**
+ * Compile a list of address-pattern strings into a matcher.
+ * Empty list → matcher rejects every address (the explicit-allow
+ * default per Q-P4-1).
+ */
+function compileSenderAllowlist(patterns) {
+    if (patterns.length === 0) {
+        return {
+            isAllowed: () => false,
+            size: () => 0,
+        };
+    }
+    const regexes = patterns
+        .map((p) => p.trim().toLowerCase())
+        .filter((p) => p.length > 0)
+        .map(patternToRegex);
+    return {
+        isAllowed(fromAddress) {
+            const addr = (fromAddress ?? '').trim().toLowerCase();
+            if (!addr)
+                return false;
+            for (const re of regexes)
+                if (re.test(addr))
+                    return true;
+            return false;
+        },
+        size: () => regexes.length,
+    };
+}
+/**
+ * Convert a sender glob pattern into a case-insensitive RegExp
+ * anchored at both ends. Only `*` is supported (matches zero or
+ * more characters that are NOT a separator we care about — but
+ * since email addresses don't have hierarchical separators like
+ * filesystems do, `*` is greedy across the whole local-part or
+ * domain). Escape every other regex meta-char.
+ */
+function patternToRegex(pat) {
+    // Escape regex specials except `*`, then convert `*` to `.*`.
+    const escaped = pat.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp('^' + escaped + '$');
+}

package/dist/core/v4/daemon/triggers/email/automatedSender.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/triggers/email/automatedSender.ts — v4.5 Phase 4a.
+ *
+ * Detects mail from automated systems (noreply addresses, bounce
+ * notifications, mailing-list digests, calendar invites, etc.).
+ *
+ * Used at TWO points:
+ *   1. INGRESS — mark UID seen + skip (don't kick off an agent turn
+ *      to "respond" to a bounce notification).
+ *   2. OUTBOUND — any future auto-reply path (Phase 5+) MUST NEVER
+ *      reply to a sender flagged automated. This is the canonical
+ *      defense against mail loops (the gateway's notification system
+ *      bounces our reply, we reply to the bounce, ...).
+ *
+ * Two signal sources combined:
+ *   - Substring match on the From / Reply-To address (noreply, etc.)
+ *   - RFC headers: Auto-Submitted, Precedence, X-Auto-Response-Suppress,
+ *     List-Unsubscribe.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTOMATED_HEADERS = exports.NOREPLY_PATTERNS = void 0;
+exports.isAutomatedSender = isAutomatedSender;
+/** Address substrings — case-insensitive — that signal automated. */
+exports.NOREPLY_PATTERNS = Object.freeze([
+    'noreply',
+    'no-reply',
+    'no_reply',
+    'donotreply',
+    'do-not-reply',
+    'mailer-daemon',
+    'postmaster',
+    'bounce',
+    'notifications@',
+    'automated@',
+    'auto-confirm',
+    'auto-reply',
+    'automailer',
+]);
+/** RFC headers that signal bulk/automated mail. */
+exports.AUTOMATED_HEADERS = Object.freeze([
+    { header: 'Auto-Submitted', test: (v) => v.toLowerCase() !== 'no' },
+    { header: 'Precedence', test: (v) => ['bulk', 'list', 'junk'].includes(v.toLowerCase()) },
+    { header: 'X-Auto-Response-Suppress', test: (v) => v.length > 0 },
+    { header: 'List-Unsubscribe', test: (v) => v.length > 0 },
+]);
+/**
+ * Return true when the sender appears to be an automated system.
+ *
+ * - `fromAddress` is the bare address (e.g. 'noreply@github.com'),
+ *   NOT a display-name-decorated form. Caller should extract via
+ *   mailparser's `parsed.from?.value[0]?.address`.
+ * - `headers` is a case-INSENSITIVE map. mailparser provides
+ *   `parsed.headers` as a Map with lowercased keys; pass that
+ *   normalized to `Record<string, string>` (multi-value headers
+ *   pick the first value).
+ */
+function isAutomatedSender(fromAddress, headers) {
+    const addr = (fromAddress ?? '').toLowerCase();
+    for (const p of exports.NOREPLY_PATTERNS)
+        if (addr.includes(p))
+            return true;
+    for (const r of exports.AUTOMATED_HEADERS) {
+        // Match case-insensitively against both the exact-case header
+        // name and the lowercased form so callers don't have to remember
+        // mailparser's specific quirk.
+        const v = headers[r.header] ?? headers[r.header.toLowerCase()];
+        if (typeof v === 'string' && v.length > 0 && r.test(v))
+            return true;
+    }
+    return false;
+}

package/dist/core/v4/daemon/triggers/email/emailSeenStore.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/triggers/email/emailSeenStore.ts — v4.5 Phase 4a.
+ *
+ * Writer + reader for the `email_seen` table. Cross-restart authority
+ * for "have we processed this UID before?" + forensic audit trail.
+ *
+ * UNIQUE(route_id, uid_validity, uid) at the schema layer dedups
+ * concurrent or repeated writes for the same UID. The status field
+ * records WHY a UID was seen even when no trigger_event was emitted
+ * (skipped due to automated sender, allowlist, subject filter, etc.).
+ *
+ * Retention: AIDEN_DAEMON_EMAIL_RETENTION_DAYS env (default 30).
+ * Sweep runs on boot + daily.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEmailSeenStore = createEmailSeenStore;
+function rowToTs(r) {
+    return {
+        id: r.id,
+        routeId: r.route_id,
+        mailbox: r.mailbox,
+        uidValidity: r.uid_validity,
+        uid: r.uid,
+        messageId: r.message_id,
+        fromAddress: r.from_address,
+        subject: r.subject,
+        receivedAt: r.received_at,
+        processedAt: r.processed_at,
+        triggerEventId: r.trigger_event_id,
+        status: r.status,
+    };
+}
+function createEmailSeenStore(opts) {
+    const db = opts.db;
+    return {
+        record(input) {
+            const now = Date.now();
+            // INSERT OR IGNORE returns 0 rows changed on conflict; in that
+            // case we look up the existing row id.
+            const r = db
+                .prepare(`INSERT OR IGNORE INTO email_seen
+             (route_id, mailbox, uid_validity, uid, message_id,
+              from_address, subject, received_at, processed_at,
+              trigger_event_id, status)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(input.routeId, input.mailbox, input.uidValidity, input.uid, input.messageId, input.fromAddress, input.subject, input.receivedAt, now, input.triggerEventId, input.status);
+            if (r.changes > 0)
+                return Number(r.lastInsertRowid);
+            const existing = db
+                .prepare(`SELECT id FROM email_seen WHERE route_id = ? AND uid_validity = ? AND uid = ?`)
+                .get(input.routeId, input.uidValidity, input.uid);
+            if (!existing) {
+                throw new Error('emailSeenStore.record: INSERT OR IGNORE skipped + no existing row found');
+            }
+            return existing.id;
+        },
+        get(routeId, uidValidity, uid) {
+            const r = db
+                .prepare(`SELECT * FROM email_seen WHERE route_id = ? AND uid_validity = ? AND uid = ?`)
+                .get(routeId, uidValidity, uid);
+            return r ? rowToTs(r) : null;
+        },
+        list(routeId, limit = 100) {
+            const rows = db
+                .prepare(`SELECT * FROM email_seen WHERE route_id = ?
+            ORDER BY received_at DESC LIMIT ?`)
+                .all(routeId, limit);
+            return rows.map(rowToTs);
+        },
+        sweep(retentionDays, now) {
+            const cutoff = (now ?? Date.now()) - retentionDays * 24 * 60 * 60 * 1000;
+            const r = db
+                .prepare(`DELETE FROM email_seen WHERE received_at < ?`)
+                .run(cutoff);
+            return { deleted: r.changes };
+        },
+        countForRoute(routeId) {
+            const r = db
+                .prepare(`SELECT COUNT(*) AS c FROM email_seen WHERE route_id = ?`)
+                .get(routeId);
+            return r.c;
+        },
+        isMessageIdSeen(messageId) {
+            if (!messageId)
+                return false;
+            const r = db
+                .prepare(`SELECT 1 FROM email_seen WHERE message_id = ? LIMIT 1`)
+                .get(messageId);
+            return r !== undefined;
+        },
+    };
+}

package/dist/core/v4/daemon/triggers/email/emailSpec.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/triggers/email/emailSpec.ts — v4.5 Phase 4a.
+ *
+ * Typed spec for source='email' triggers, stored in
+ * triggers.spec_json. Parse + validation + defaults.
+ *
+ * Required:
+ *   - name
+ *   - imap.{host, user, password}
+ *   - allowedSenders (at least one entry) — Q-P4-1 (a) reject-all
+ *     default; users opt in to specific senders. Glob-style patterns
+ *     supported (see allowlist.ts).
+ *
+ * Password handling: stored RAW in spec_json. daemon.db is chmod 600
+ * on POSIX (see db/connection.ts since Phase 3). Encryption-at-rest
+ * deferred to v4.6+ per Q-P4-4 (a). aiden trigger show deliberately
+ * omits the password.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_IMAP = exports.DEFAULT_EMAIL_SPEC = void 0;
+exports.parseEmailSpec = parseEmailSpec;
+exports.DEFAULT_EMAIL_SPEC = {
+    mailbox: 'INBOX',
+    pollIntervalMs: 15000,
+    maxBodyBytes: 1048576,
+    deliverOnly: false,
+    attachmentPolicy: 'skip',
+};
+exports.DEFAULT_IMAP = {
+    port: 993,
+    tls: true,
+    authTimeoutMs: 10000,
+};
+function parseEmailSpec(raw) {
+    const obj = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+        throw new Error('EmailSpec: input must be an object');
+    }
+    const o = obj;
+    const name = typeof o.name === 'string' && o.name.length > 0 ? o.name : '';
+    if (!name)
+        throw new Error('EmailSpec: name required');
+    const imapRaw = (o.imap && typeof o.imap === 'object') ? o.imap : {};
+    const imap = {
+        host: requireStr(imapRaw.host, 'imap.host'),
+        user: requireStr(imapRaw.user, 'imap.user'),
+        password: requireStr(imapRaw.password, 'imap.password'),
+        port: sanitizeNum(imapRaw.port, exports.DEFAULT_IMAP.port, 1),
+        tls: typeof imapRaw.tls === 'boolean' ? imapRaw.tls : exports.DEFAULT_IMAP.tls,
+        authTimeoutMs: sanitizeNum(imapRaw.authTimeoutMs, exports.DEFAULT_IMAP.authTimeoutMs, 1000),
+    };
+    const allowedSenders = Array.isArray(o.allowedSenders)
+        ? o.allowedSenders.filter((s) => typeof s === 'string' && s.trim().length > 0)
+        : [];
+    if (allowedSenders.length === 0) {
+        throw new Error('EmailSpec: allowedSenders required (at least one --allow-sender entry). Use "*@your-domain.com" for a whole domain.');
+    }
+    const allowedSubjectPatterns = Array.isArray(o.allowedSubjectPatterns)
+        ? o.allowedSubjectPatterns.filter((s) => typeof s === 'string')
+        : undefined;
+    if (allowedSubjectPatterns) {
+        // Compile-test each pattern at parse time so bad regexes surface early.
+        for (const p of allowedSubjectPatterns) {
+            try {
+                new RegExp(p);
+            }
+            catch (e) {
+                throw new Error(`EmailSpec: allowedSubjectPatterns has invalid regex ${JSON.stringify(p)}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+    }
+    return {
+        name,
+        imap,
+        mailbox: typeof o.mailbox === 'string' && o.mailbox.length > 0 ? o.mailbox : exports.DEFAULT_EMAIL_SPEC.mailbox,
+        pollIntervalMs: sanitizeNum(o.pollIntervalMs, exports.DEFAULT_EMAIL_SPEC.pollIntervalMs, 1000),
+        allowedSenders,
+        allowedSubjectPatterns,
+        maxBodyBytes: sanitizeNum(o.maxBodyBytes, exports.DEFAULT_EMAIL_SPEC.maxBodyBytes, 1024),
+        promptTemplate: typeof o.promptTemplate === 'string' ? o.promptTemplate : undefined,
+        deliverOnly: typeof o.deliverOnly === 'boolean' ? o.deliverOnly : exports.DEFAULT_EMAIL_SPEC.deliverOnly,
+        attachmentPolicy: sanitizeAttachmentPolicy(o.attachmentPolicy),
+    };
+}
+function requireStr(v, label) {
+    if (typeof v !== 'string' || v.length === 0) {
+        throw new Error(`EmailSpec: ${label} required (non-empty string)`);
+    }
+    return v;
+}
+function sanitizeNum(v, fallback, min) {
+    if (typeof v !== 'number' || !Number.isFinite(v) || v < min)
+        return fallback;
+    return v;
+}
+function sanitizeAttachmentPolicy(v) {
+    if (v === 'skip' || v === 'inline-text' || v === 'save-to-tmp')
+        return v;
+    return exports.DEFAULT_EMAIL_SPEC.attachmentPolicy;
+}