@holon-run/agentinbox 1.5.2 → 1.7.0

package/README.md

@@ -299,6 +299,22 @@ that database next to the DB path (for example,
 `~/.agentinbox/agentinbox.sqlite.pre-v1.<timestamp>.bak`) and starts with a
 fresh v1 database; pre-v1 local data is not imported.
 
+## Database Backups
+
+Startup backups are event-driven, not unconditional:
+
+- before pending schema migrations run, a full backup is written to
+  `<db>.pre-migrate-v<N>.bak` (bounded by `AGENTINBOX_MIGRATION_BACKUP_KEEP`,
+  default 5; `0` keeps all)
+- `agentinbox backup [--home DIR] [--state PATH]` writes a manual snapshot to
+  `<db>.bak` on demand, for scheduled or pre-upgrade snapshots
+- regular opens verify the database with `PRAGMA quick_check` and escalate to
+  a full `integrity_check` only when the quick pass fails; recovery considers
+  manual and pre-migration backups, most recent first
+
+Setting `AGENTINBOX_STARTUP_BACKUP=1` restores the legacy behavior of backing
+up (and fully checking) the database on every open.
+
 ## License
 
 Apache-2.0

package/dist/src/adapters.js

@@ -5,6 +5,7 @@ const paths_1 = require("./paths");
 const feishu_1 = require("./sources/feishu");
 const github_1 = require("./sources/github");
 const telegram_1 = require("./sources/telegram");
+const email_1 = require("./sources/email");
 const remote_1 = require("./sources/remote");
 const remote_modules_1 = require("./sources/remote_modules");
 const source_resolution_1 = require("./source_resolution");
@@ -42,6 +43,7 @@ class AdapterRegistry {
     feishuDelivery;
     githubDelivery = new github_1.GithubDeliveryAdapter();
     telegramDelivery;
+    emailDelivery;
     homeDir;
     remoteModuleRegistry;
     constructor(store, appendSourceEvent, options) {
@@ -51,6 +53,7 @@ class AdapterRegistry {
         });
         this.feishuDelivery = new feishu_1.FeishuDeliveryAdapter(options?.feishuClient);
         this.telegramDelivery = new telegram_1.TelegramDeliveryAdapter(options?.telegramClient);
+        this.emailDelivery = new email_1.EmailDeliveryAdapter(options?.emailClient);
         this.remoteSource = new remote_1.RemoteSourceRuntime(store, appendSourceEvent, {
             homeDir: this.homeDir,
             client: options?.remoteSourceClient,
@@ -76,6 +79,9 @@ class AdapterRegistry {
         if (type === "telegram_bot") {
             return this.remoteSource;
         }
+        if (type === "email_mailbox") {
+            return this.remoteSource;
+        }
         return this.localEventSource;
     }
     deliveryAdapterFor(provider) {
@@ -88,6 +94,9 @@ class AdapterRegistry {
         if (provider === "telegram") {
             return this.telegramDelivery;
         }
+        if (provider === "email") {
+            return this.emailDelivery;
+        }
         return this.defaultDelivery;
     }
     async start() {
@@ -251,6 +260,9 @@ class AdapterRegistry {
         if (handle.provider === "telegram") {
             return this.remoteModuleRegistry.resolve(syntheticBuiltinSource("telegram_bot"), this.homeDir);
         }
+        if (handle.provider === "email") {
+            return this.remoteModuleRegistry.resolve(syntheticBuiltinSource("email_mailbox"), this.homeDir);
+        }
         return null;
     }
 }
@@ -262,6 +274,7 @@ function isExplicitFollowPreviewRef(value) {
         value === "github_repo_ci" ||
         value === "feishu_bot" ||
         value === "telegram_bot" ||
+        value === "email_mailbox" ||
         value.startsWith("remote:"));
 }
 function hasRemoteSourceModulePath(config) {

package/dist/src/cli.js

@@ -60,6 +60,14 @@ async function main() {
         await runDaemon(normalized.slice(1));
         return;
     }
+    if (command === "backup") {
+        if (hasHelpFlag(normalized.slice(1))) {
+            printHelp(["backup"]);
+            return;
+        }
+        await runBackup(normalized.slice(1));
+        return;
+    }
     if (hasHelpFlag(normalized.slice(1))) {
         printHelp([command]);
         return;
@@ -971,6 +979,7 @@ const COMMAND_SHELL_SPECS = [
     { name: "subscription", group: true, summary: "Manage source subscriptions." },
     { name: "inbox", group: true, summary: "Read and manage agent inboxes." },
     { name: "gc", group: false, summary: "Run garbage collection." },
+    { name: "backup", group: false, summary: "Write a local database backup snapshot." },
     { name: "deliver", group: true, summary: "Send outbound delivery actions." },
     { name: "status", group: false, summary: "Show daemon status." },
     { name: "version", group: false, summary: "Show CLI version." },
@@ -1006,6 +1015,25 @@ function parseCommanderShell(args) {
         isBareGroup: Boolean(COMMAND_SHELL_SPECS.find((item) => item.name === spec?.name())?.group && args.length === 1),
     };
 }
+async function runBackup(args) {
+    const serveConfig = (0, paths_1.resolveServeConfig)({
+        env: process.env,
+        homeDirOverride: takeFlagValue(args, "--home"),
+        statePathOverride: takeFlagValue(args, "--state"),
+    });
+    const store = await store_1.AgentInboxStore.open(serveConfig.dbPath);
+    try {
+        const backupPath = await store.backupDatabase();
+        console.log((0, util_1.jsonResponse)({
+            ok: true,
+            dbPath: serveConfig.dbPath,
+            backupPath,
+        }));
+    }
+    finally {
+        store.close();
+    }
+}
 async function runServe(args) {
     const port = parseOptionalNumber(takeFlagValue(args, "--port"));
     const homeOverride = takeFlagValue(args, "--home");
@@ -1677,6 +1705,14 @@ Usage:
   agentinbox daemon start [--home ~/.agentinbox] [--socket ~/.agentinbox/agentinbox.sock] [--log-level error|warn|info|debug|trace]
   agentinbox daemon stop [--home ~/.agentinbox] [--socket ~/.agentinbox/agentinbox.sock]
   agentinbox daemon status [--home ~/.agentinbox] [--socket ~/.agentinbox/agentinbox.sock]
+`,
+        backup: `agentinbox backup
+
+Usage:
+  agentinbox backup [--home ~/.agentinbox] [--state ~/.agentinbox/agentinbox.sqlite]
+
+Writes a verified snapshot to <db>.bak (replaces the previous manual backup).
+Pre-migration backups (<db>.pre-migrate-v<N>.bak) are created automatically.
 `,
         host: `agentinbox host
 

package/dist/src/service.js

@@ -3313,7 +3313,8 @@ function sourceTypeForPreviewRef(sourceRef) {
         sourceRef === "github_repo" ||
         sourceRef === "github_repo_ci" ||
         sourceRef === "feishu_bot" ||
-        sourceRef === "telegram_bot") {
+        sourceRef === "telegram_bot" ||
+        sourceRef === "email_mailbox") {
         return sourceRef;
     }
     if (sourceRef.startsWith("remote:")) {
@@ -3615,6 +3616,9 @@ function providerForSourceType(sourceType) {
     if (sourceType === "telegram_bot") {
         return "telegram";
     }
+    if (sourceType === "email_mailbox") {
+        return "email";
+    }
     return null;
 }
 function authHeaders(auth) {
@@ -4209,6 +4213,8 @@ function listHostStreamKinds(hostType) {
             return ["message_events"];
         case "telegram":
             return ["message_updates"];
+        case "email":
+            return ["message_events"];
         case "local_event":
             return ["events"];
         case "remote_source":
@@ -4218,6 +4224,7 @@ function listHostStreamKinds(hostType) {
 const KNOWN_DELIVERY_SURFACES = {
     feishu: ["message_reply", "chat_message"],
     github: ["issue_comment", "pull_request_comment", "review_comment"],
+    email: ["message_reply", "message_send"],
 };
 function unsupportedDeliverySurfaceMessage(handle) {
     const supported = KNOWN_DELIVERY_SURFACES[handle.provider];
@@ -4298,6 +4305,12 @@ function getHostConfigFields(hostType) {
                 { name: "tokenEnv", type: "string", description: "Environment variable containing the Telegram Bot API token.", required: false },
                 { name: "botUsername", type: "string", description: "Optional bot username used for shared host identity.", required: false },
             ];
+        case "email":
+            return [
+                { name: "uxcAuth", type: "string", description: "UXC auth profile holding mailbox credentials.", required: false },
+                { name: "smtpEndpoint", type: "string", description: "Default smtp:// endpoint for outbound delivery.", required: false },
+                { name: "fromAddress", type: "string", description: "Default outbound From address.", required: false },
+            ];
         case "local_event":
             return [];
         case "remote_source":
@@ -4317,6 +4330,9 @@ function sourceTypeForStreamRegistration(hostType, streamKind) {
     if (hostType === "telegram") {
         return "telegram_bot";
     }
+    if (hostType === "email") {
+        return "email_mailbox";
+    }
     if (hostType === "local_event") {
         return "local_event";
     }

package/dist/src/source_hosts.js

@@ -60,6 +60,22 @@ function resolveSourceRegistration(input) {
             sourceType: input.sourceType,
         };
     }
+    if (input.sourceType === "email_mailbox") {
+        const provider = stringOrDefault(config.provider, "imap");
+        return {
+            hostType: "email",
+            hostKey: `email:${provider}:${stringOrDefault(config.account, stringOrDefault(config.uxcAuth, input.sourceKey))}`,
+            hostConfig: {
+                ...(valueOrUndefined(config.uxcAuth) ? { uxcAuth: config.uxcAuth } : {}),
+                ...(valueOrUndefined(config.smtpEndpoint) ? { smtpEndpoint: config.smtpEndpoint } : {}),
+                ...(valueOrUndefined(config.fromAddress) ? { fromAddress: config.fromAddress } : {}),
+            },
+            streamKind: "message_events",
+            streamKey: input.sourceKey,
+            streamConfig: config,
+            sourceType: input.sourceType,
+        };
+    }
     if (input.sourceType === "local_event") {
         return {
             hostType: "local_event",

package/dist/src/source_schema.js

@@ -189,6 +189,57 @@ const SOURCE_SCHEMAS = {
             { name: "endpoint", type: "string", required: false, description: "Optional Telegram Bot API endpoint override." },
         ],
     },
+    email_mailbox: {
+        sourceType: "email_mailbox",
+        metadataFields: [
+            { name: "provider", type: "string", description: "Email provider: imap, gmail, graph, or jmap." },
+            { name: "account", type: "string", description: "Mailbox account alias." },
+            { name: "mailbox", type: "string", description: "Mailbox name such as INBOX." },
+            { name: "messageId", type: "string|null", description: "RFC Message-ID header when present." },
+            { name: "providerMessageId", type: "string|null", description: "Provider-native message id (IMAP UID or provider message id)." },
+            { name: "threadId", type: "string|null", description: "Thread reference derived from References/In-Reply-To headers." },
+            { name: "from", type: "string|null", description: "Normalized sender address." },
+            { name: "fromName", type: "string|null", description: "Sender display name when present." },
+            { name: "to", type: "object[]", description: "Normalized recipients with address and optional name." },
+            { name: "cc", type: "object[]", description: "Normalized cc recipients with address and optional name." },
+            { name: "subject", type: "string|null", description: "Message subject." },
+            { name: "textPreview", type: "string|null", description: "Short body snippet." },
+            { name: "date", type: "string|null", description: "Message date header value." },
+            { name: "hasAttachments", type: "boolean", description: "Whether the message carries attachments." },
+            { name: "attachmentCount", type: "number|null", description: "Attachment count; null when the provider did not expand attachment metadata." },
+            { name: "attachments", type: "object[]", description: "Attachment metadata entries with opaque retrieval handles; binary content is never embedded." },
+        ],
+        payloadExamples: [
+            {
+                type: "email_event",
+                version: "v1",
+                provider: "imap",
+                account: "user@example.com",
+                mailbox: "INBOX",
+                event_kind: "message_received",
+                message: {
+                    uid: "42",
+                    message_id: "<msg@example.com>",
+                    from: "sender@example.com",
+                    to: [{ raw: "user@example.com" }],
+                    subject: "Quarterly report",
+                    snippet: "Please review...",
+                },
+            },
+        ],
+        eventVariantExamples: ["email.message.received"],
+        configFields: [
+            { name: "provider", type: "string", required: true, description: "Email provider: imap, gmail, graph, or jmap." },
+            { name: "uxcAuth", type: "string", required: true, description: "UXC auth profile name holding mailbox credentials; credentials never inline." },
+            { name: "endpoint", type: "string", required: false, description: "imap:// or imaps:// endpoint for imap; provider API endpoint for gmail/graph/jmap (jmap requires it)." },
+            { name: "account", type: "string", required: false, description: "Account alias; defaults to the auth profile username." },
+            { name: "mailbox", type: "string", required: false, description: "Mailbox to watch; defaults to INBOX." },
+            { name: "pollIntervalSecs", type: "number", required: false, description: "Provider poll interval in seconds (min 15, default 60)." },
+            { name: "smtpEndpoint", type: "string", required: false, description: "Default smtp:// endpoint for outbound reply/send delivery." },
+            { name: "fromAddress", type: "string", required: false, description: "Default outbound From address for delivery." },
+            { name: "addressAllowlist", type: "string[]", required: false, description: "Optional from/to address allowlist applied before inbox routing." },
+        ],
+    },
 };
 function getSourceSchema(sourceType) {
     const schema = SOURCE_SCHEMAS[sourceType];

package/dist/src/sources/email.js

@@ -0,0 +1,532 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailDeliveryAdapter = exports.RpcEmailUxcClient = exports.GRAPH_MESSAGES_ENDPOINT = exports.GMAIL_MESSAGES_ENDPOINT = exports.EMAIL_EVENT_VERSION = exports.EMAIL_EVENT_TYPE = exports.EMAIL_MAILBOX_DEFAULT_POLL_INTERVAL_SECS = exports.EMAIL_DEFAULT_MAILBOX = void 0;
+exports.parseEmailMailboxSourceConfig = parseEmailMailboxSourceConfig;
+exports.buildEmailMailboxSourceSpec = buildEmailMailboxSourceSpec;
+exports.normalizeEmailMailboxEvent = normalizeEmailMailboxEvent;
+exports.emailDeliveryOperationsForHandle = emailDeliveryOperationsForHandle;
+exports.invokeEmailDeliveryOperation = invokeEmailDeliveryOperation;
+const uxc_daemon_client_1 = require("@holon-run/uxc-daemon-client");
+exports.EMAIL_DEFAULT_MAILBOX = "INBOX";
+exports.EMAIL_MAILBOX_DEFAULT_POLL_INTERVAL_SECS = 60;
+exports.EMAIL_EVENT_TYPE = "email_event";
+exports.EMAIL_EVENT_VERSION = "v1";
+exports.GMAIL_MESSAGES_ENDPOINT = "https://gmail.googleapis.com/gmail/v1/users/me/messages";
+exports.GRAPH_MESSAGES_ENDPOINT = "https://graph.microsoft.com/v1.0/me/messages?$expand=attachments";
+const EMAIL_MAILBOX_PROVIDERS = new Set(["imap", "gmail", "graph", "jmap"]);
+const EMAIL_DEFAULT_ENDPOINTS = {
+    gmail: exports.GMAIL_MESSAGES_ENDPOINT,
+    graph: exports.GRAPH_MESSAGES_ENDPOINT,
+};
+function parseEmailMailboxSourceConfig(source) {
+    const config = source.config ?? {};
+    const providerRaw = asString(config.provider) ?? asString(config.emailProvider);
+    if (!providerRaw) {
+        throw new Error("email_mailbox requires config.provider (imap, gmail, graph, or jmap)");
+    }
+    const provider = providerRaw.trim().toLowerCase();
+    if (!EMAIL_MAILBOX_PROVIDERS.has(provider)) {
+        throw new Error(`email_mailbox config.provider must be one of imap, gmail, graph, jmap; got ${providerRaw}`);
+    }
+    const endpointRaw = asString(config.endpoint);
+    let endpoint;
+    if (provider === "imap") {
+        if (!endpointRaw) {
+            throw new Error("email_mailbox with provider=imap requires config.endpoint (imap:// or imaps://)");
+        }
+        if (!/^imaps?:\/\//i.test(endpointRaw)) {
+            throw new Error(`email_mailbox imap endpoint must start with imap:// or imaps://; got ${endpointRaw}`);
+        }
+        endpoint = endpointRaw;
+    }
+    else {
+        const fallback = EMAIL_DEFAULT_ENDPOINTS[provider];
+        if (endpointRaw) {
+            if (!/^https?:\/\//i.test(endpointRaw)) {
+                throw new Error(`email_mailbox ${provider} endpoint must start with http:// or https://; got ${endpointRaw}`);
+            }
+            endpoint = endpointRaw;
+        }
+        else if (fallback) {
+            endpoint = fallback;
+        }
+        else {
+            throw new Error(`email_mailbox with provider=${provider} requires config.endpoint (${provider} API URL)`);
+        }
+    }
+    const uxcAuth = asString(config.uxcAuth) ?? asString(config.auth);
+    if (!uxcAuth || uxcAuth.trim().length === 0) {
+        throw new Error("email_mailbox requires config.uxcAuth (UXC auth profile name; credentials stay in UXC)");
+    }
+    const pollIntervalRaw = config.pollIntervalSecs;
+    let pollIntervalSecs = exports.EMAIL_MAILBOX_DEFAULT_POLL_INTERVAL_SECS;
+    if (pollIntervalRaw !== undefined && pollIntervalRaw !== null) {
+        const parsed = numberFromUnknown(pollIntervalRaw);
+        if (parsed === undefined || !Number.isInteger(parsed) || parsed < 15) {
+            throw new Error(`email_mailbox config.pollIntervalSecs must be an integer >= 15; got ${String(pollIntervalRaw)}`);
+        }
+        pollIntervalSecs = parsed;
+    }
+    const smtpEndpoint = asString(config.smtpEndpoint);
+    if (smtpEndpoint && !/^smtp:\/\/./i.test(smtpEndpoint)) {
+        throw new Error(`email_mailbox config.smtpEndpoint must use smtp:// (uxc SMTP surface); got ${smtpEndpoint}`);
+    }
+    const fromAddress = asString(config.fromAddress);
+    if (fromAddress && !fromAddress.includes("@")) {
+        throw new Error(`email_mailbox config.fromAddress must be an email address; got ${fromAddress}`);
+    }
+    const account = asString(config.account) ?? undefined;
+    if (account !== undefined && account.trim().length === 0) {
+        throw new Error("email_mailbox config.account must be a non-empty string when provided");
+    }
+    const mailbox = asString(config.mailbox) ?? exports.EMAIL_DEFAULT_MAILBOX;
+    if (mailbox.trim().length === 0) {
+        throw new Error("email_mailbox config.mailbox must be a non-empty string when provided");
+    }
+    const addressAllowlist = asStringArray(config.addressAllowlist ?? config.addressAllowList);
+    return {
+        provider: provider,
+        endpoint,
+        uxcAuth: uxcAuth.trim(),
+        account: account?.trim() || undefined,
+        mailbox,
+        pollIntervalSecs,
+        ...(smtpEndpoint ? { smtpEndpoint } : {}),
+        ...(fromAddress ? { fromAddress } : {}),
+        ...(addressAllowlist && addressAllowlist.length > 0 ? { addressAllowlist } : {}),
+    };
+}
+function buildEmailMailboxSourceSpec(config) {
+    const args = compactRecord({
+        mailbox: config.mailbox,
+        account: config.account,
+    });
+    if (config.provider === "imap") {
+        return {
+            endpoint: config.endpoint,
+            mode: "stream",
+            transport_hint: "email_imap_idle",
+            args,
+            options: {
+                auth: config.uxcAuth,
+                artifact_compaction: false,
+            },
+        };
+    }
+    return {
+        endpoint: config.endpoint,
+        mode: "poll",
+        transport_hint: "email_provider_poll",
+        args: {
+            provider: config.provider,
+            ...args,
+        },
+        poll_config: {
+            interval_secs: config.pollIntervalSecs,
+            extract_items_pointer: "/items",
+            checkpoint_strategy: {
+                type: "item_key",
+                item_key_pointer: "/message/uid",
+            },
+        },
+        options: {
+            auth: config.uxcAuth,
+            artifact_compaction: false,
+        },
+    };
+}
+function emailActorParts(value) {
+    if (typeof value === "string") {
+        const raw = value.trim();
+        if (raw.length === 0) {
+            return null;
+        }
+        const angled = raw.match(/<([^>]+)>\s*$/);
+        if (angled) {
+            const name = raw.slice(0, raw.lastIndexOf("<")).trim().replace(/^"|"$/g, "").trim();
+            return { address: angled[1].trim(), name: name.length > 0 ? name : null, raw };
+        }
+        return { address: raw, name: null, raw };
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    if (typeof record.raw === "string") {
+        return emailActorParts(record.raw);
+    }
+    const address = asString(record.address) ?? asString(record.email);
+    if (address) {
+        return { address, name: asString(record.name), raw: address };
+    }
+    return null;
+}
+function emailActorAddresses(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const addresses = [];
+    for (const item of value) {
+        const parts = emailActorParts(item);
+        if (parts?.address) {
+            addresses.push(parts.address);
+        }
+    }
+    return addresses;
+}
+function emailActorList(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((item) => emailActorParts(item))
+        .filter((parts) => Boolean(parts?.address))
+        .map((parts) => ({
+        address: parts.address,
+        ...(parts.name ? { name: parts.name } : {}),
+    }));
+}
+function normalizeEmailMailboxEvent(source, config, raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return null;
+    }
+    const payload = raw;
+    if (payload.type !== exports.EMAIL_EVENT_TYPE) {
+        return null;
+    }
+    const version = asString(payload.version);
+    if (version !== null && version !== exports.EMAIL_EVENT_VERSION) {
+        return null;
+    }
+    if (payload.event_kind !== "message_received") {
+        return null;
+    }
+    const message = asRecord(payload.message);
+    if (Object.keys(message).length === 0) {
+        return null;
+    }
+    const provider = asString(payload.provider) ?? config.provider;
+    const account = asString(payload.account) ?? config.account ?? config.uxcAuth;
+    const mailbox = asString(payload.mailbox) ?? config.mailbox;
+    const uid = stringFromUnknown(message.uid);
+    const messageId = asString(message.message_id) ?? uid;
+    if (!uid && !messageId) {
+        return null;
+    }
+    const fromParts = emailActorParts(message.from);
+    const toAddresses = emailActorAddresses(message.to);
+    if (config.addressAllowlist &&
+        config.addressAllowlist.length > 0 &&
+        !addressMatchesAllowlist(config.addressAllowlist, fromParts?.address ?? null, toAddresses)) {
+        return null;
+    }
+    const attachments = Array.isArray(message.attachments)
+        ? message.attachments.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item))
+        : [];
+    const attachmentCountRaw = message.attachment_count;
+    const attachmentCount = numberFromUnknown(attachmentCountRaw) ?? null;
+    const date = asString(message.date);
+    return {
+        sourceId: source.sourceId,
+        sourceNativeId: `email:${provider}:${account}:${mailbox}:${uid ?? messageId}`,
+        eventVariant: "email.message.received",
+        occurredAt: occurredAtFromEmailDate(date),
+        metadata: {
+            provider,
+            account,
+            mailbox,
+            messageId: messageId ?? null,
+            providerMessageId: uid ?? null,
+            threadId: asString(message.thread_id),
+            from: fromParts ? (fromParts.address ?? fromParts.raw) : null,
+            fromName: fromParts?.name ?? null,
+            to: emailActorList(message.to),
+            cc: emailActorList(message.cc),
+            subject: asString(message.subject),
+            textPreview: asString(message.snippet),
+            date,
+            hasAttachments: attachments.length > 0 || message.has_attachments === true,
+            attachmentCount,
+            attachments,
+        },
+        rawPayload: payload,
+        deliveryHandle: {
+            provider: "email",
+            surface: "message_reply",
+            targetRef: fromParts ? (fromParts.address ?? fromParts.raw) : "",
+            threadRef: messageId ?? null,
+            replyMode: "reply",
+        },
+    };
+}
+function addressMatchesAllowlist(allowlist, fromAddress, toAddresses) {
+    const normalized = allowlist
+        .map((entry) => entry.trim().toLowerCase())
+        .filter((entry) => entry.length > 0);
+    if (normalized.length === 0) {
+        return true;
+    }
+    const lowerFrom = fromAddress?.toLowerCase() ?? null;
+    if (lowerFrom && normalized.includes(lowerFrom)) {
+        return true;
+    }
+    return toAddresses.some((address) => normalized.includes(address.toLowerCase()));
+}
+function occurredAtFromEmailDate(date) {
+    if (date) {
+        const parsed = Date.parse(date);
+        if (Number.isFinite(parsed)) {
+            return new Date(parsed).toISOString();
+        }
+    }
+    return new Date().toISOString();
+}
+class RpcEmailUxcClient {
+    client;
+    constructor(client = new uxc_daemon_client_1.UxcDaemonClient({ env: process.env })) {
+        this.client = client;
+    }
+    request(method, params) {
+        return this.client.request(method, params);
+    }
+}
+exports.RpcEmailUxcClient = RpcEmailUxcClient;
+function emailDeliveryOperationsForHandle(handle) {
+    if (handle.provider !== "email") {
+        return [];
+    }
+    if (handle.surface !== "message_reply" && handle.surface !== "message_send") {
+        return [];
+    }
+    const isReply = handle.surface === "message_reply";
+    const commonProperties = {
+        text: { type: "string", minLength: 1 },
+        subject: { type: "string", minLength: 1 },
+        to: { type: "array", items: { type: "string", minLength: 1 } },
+        cc: { type: "array", items: { type: "string", minLength: 1 } },
+        from: { type: "string", minLength: 1 },
+        smtpEndpoint: { type: "string", minLength: 1 },
+        uxcAuth: { type: "string", minLength: 1 },
+        correlationKey: { type: "string", minLength: 1 },
+    };
+    const operations = [
+        {
+            name: "send_text",
+            title: isReply ? "Reply With Text" : "Send Text Email",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["text", "subject"],
+                properties: commonProperties,
+            },
+            canonicalTextAlias: true,
+        },
+    ];
+    if (isReply) {
+        operations.push({
+            name: "reply_text",
+            title: "Reply With Text (Threaded)",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["text"],
+                properties: {
+                    ...commonProperties,
+                    replyAll: { type: "boolean" },
+                    inReplyTo: { type: "string", minLength: 1 },
+                },
+            },
+        });
+    }
+    return operations;
+}
+async function invokeEmailDeliveryOperation(handle, operation, input, options) {
+    if (handle.provider !== "email") {
+        throw new Error(`email delivery operation requires an email handle, got ${handle.provider}`);
+    }
+    if (operation !== "send_text" && operation !== "reply_text") {
+        throw new Error(`unknown email delivery operation: ${operation}`);
+    }
+    const isReply = operation === "reply_text" || handle.surface === "message_reply";
+    const text = asString(input.text);
+    if (!text || text.trim().length === 0) {
+        throw new Error(`${operation} requires input.text`);
+    }
+    const config = sourceConfigOrNull(options?.source);
+    const to = asStringArray(input.to) ?? (handle.targetRef ? [handle.targetRef] : []);
+    const cc = asStringArray(input.cc) ?? [];
+    if (to.length === 0 && cc.length === 0) {
+        throw new Error(`${operation} requires at least one recipient in input.to (or input.cc)`);
+    }
+    const subject = resolveEmailSubject(operation, input, isReply);
+    const smtpEndpoint = asString(input.smtpEndpoint) ?? config?.smtpEndpoint ?? null;
+    if (!smtpEndpoint) {
+        throw new Error(`${operation} requires input.smtpEndpoint or source config smtpEndpoint (uxc supports smtp://)`);
+    }
+    const from = asString(input.from) ?? config?.fromAddress ?? addressLikeAccount(config?.account) ?? null;
+    if (!from) {
+        throw new Error(`${operation} requires input.from, source config fromAddress, or an account-like config.account value`);
+    }
+    const uxcAuth = asString(input.uxcAuth) ?? config?.uxcAuth ?? null;
+    const correlationKey = asString(input.correlationKey);
+    const inReplyTo = asString(input.inReplyTo) ?? (isReply ? handle.threadRef ?? null : null);
+    const params = compactRecord({
+        smtp_url: smtpEndpoint,
+        from,
+        to,
+        cc: cc.length > 0 ? cc : undefined,
+        subject,
+        text,
+        in_reply_to: inReplyTo ?? undefined,
+        auth: uxcAuth ?? undefined,
+        message_id: correlationKey ? correlationMessageId(correlationKey) : undefined,
+    });
+    const method = isReply ? "email.reply" : "email.send";
+    if (isReply) {
+        params.reply_handle = compactRecord({
+            message_id: handle.threadRef ?? undefined,
+            account: config?.account ?? undefined,
+            mailbox: config?.mailbox ?? undefined,
+        });
+    }
+    const client = options?.client ?? new RpcEmailUxcClient();
+    let result;
+    try {
+        result = await client.request(method, params);
+    }
+    catch (error) {
+        throw wrapEmailRpcError(error, method);
+    }
+    const note = isReply
+        ? `sent email reply${result.message_id ? ` (message-id ${result.message_id})` : ""}`
+        : `sent email${result.message_id ? ` (message-id ${result.message_id})` : ""}`;
+    return { status: "sent", note };
+}
+function resolveEmailSubject(operation, input, isReply) {
+    const subject = asString(input.subject);
+    if (!isReply) {
+        if (!subject || subject.trim().length === 0) {
+            throw new Error(`${operation} requires input.subject`);
+        }
+        return subject;
+    }
+    const base = subject && subject.trim().length > 0 ? subject.trim() : "your message";
+    if (/^re:/i.test(base)) {
+        return base;
+    }
+    return `Re: ${base}`;
+}
+function correlationMessageId(correlationKey) {
+    const trimmed = correlationKey.trim();
+    if (trimmed.startsWith("<") && trimmed.endsWith(">")) {
+        return trimmed;
+    }
+    const safe = trimmed.replace(/[<>\s]/g, "");
+    return `<agentinbox-${safe}@localhost>`;
+}
+function sourceConfigOrNull(source) {
+    if (!source || source.sourceType !== "email_mailbox") {
+        return null;
+    }
+    try {
+        return parseEmailMailboxSourceConfig(source);
+    }
+    catch {
+        return null;
+    }
+}
+function addressLikeAccount(account) {
+    if (!account) {
+        return null;
+    }
+    return account.includes("@") ? account : null;
+}
+function wrapEmailRpcError(error, method) {
+    if (error && typeof error === "object" && "code" in error) {
+        const code = error.code;
+        if (code === -32601 || code === -32602) {
+            return new Error(`connected uxc daemon does not support ${method} (code ${code}); upgrade uxc to a version with email send/reply RPC support`);
+        }
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}
+class EmailDeliveryAdapter {
+    client;
+    constructor(client) {
+        this.client = client ?? new RpcEmailUxcClient();
+    }
+    async send(request, attempt) {
+        const handle = {
+            provider: attempt.provider,
+            surface: attempt.surface,
+            targetRef: attempt.targetRef,
+            threadRef: attempt.threadRef ?? null,
+            replyMode: attempt.replyMode ?? null,
+        };
+        const result = await invokeEmailDeliveryOperation(handle, "send_text", request.payload, {
+            client: this.client,
+        });
+        return { status: "sent", note: result.note };
+    }
+}
+exports.EmailDeliveryAdapter = EmailDeliveryAdapter;
+function compactRecord(input) {
+    const output = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (Array.isArray(value) && value.length === 0) {
+            continue;
+        }
+        output[key] = value;
+    }
+    return output;
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function asString(value) {
+    return typeof value === "string" ? value : null;
+}
+function asStringArray(value) {
+    if (Array.isArray(value)) {
+        return value
+            .map((item) => stringFromUnknown(item))
+            .filter((item) => Boolean(item && item.trim().length > 0));
+    }
+    if (typeof value === "string") {
+        return value
+            .split(",")
+            .map((item) => item.trim())
+            .filter((item) => item.length > 0);
+    }
+    return null;
+}
+function stringFromUnknown(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return String(value);
+    }
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    return null;
+}
+function numberFromUnknown(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return undefined;
+}

package/dist/src/sources/remote.js

@@ -11,6 +11,7 @@ const REMOTE_SOURCE_TYPES = new Set([
     "github_repo_ci",
     "feishu_bot",
     "telegram_bot",
+    "email_mailbox",
 ]);
 const DEFAULT_SYNC_INTERVAL_MS = 2_000;
 const DEFAULT_BACKOFF_BASE_SECS = 2;

package/dist/src/sources/remote_modules.js

@@ -15,9 +15,10 @@ const github_1 = require("./github");
 const github_ci_1 = require("./github_ci");
 const feishu_1 = require("./feishu");
 const telegram_1 = require("./telegram");
+const email_1 = require("./email");
 const REMOTE_USER_MODULE_ROOT_DIR = "source-modules";
-const BUILTIN_MODULE_IDS = new Set(["builtin.github_repo", "builtin.github_repo_ci", "builtin.feishu_bot", "builtin.telegram_bot"]);
-const BUILTIN_REMOTE_SOURCE_TYPES = ["github_repo", "github_repo_ci", "feishu_bot", "telegram_bot"];
+const BUILTIN_MODULE_IDS = new Set(["builtin.github_repo", "builtin.github_repo_ci", "builtin.feishu_bot", "builtin.telegram_bot", "builtin.email_mailbox"]);
+const BUILTIN_REMOTE_SOURCE_TYPES = ["github_repo", "github_repo_ci", "feishu_bot", "telegram_bot", "email_mailbox"];
 class RemoteSourceModuleRegistry {
     moduleCache = new Map();
     githubRepoModule;
@@ -37,6 +38,9 @@ class RemoteSourceModuleRegistry {
         if (source.sourceType === "telegram_bot") {
             return Promise.resolve(TELEGRAM_BOT_MODULE);
         }
+        if (source.sourceType === "email_mailbox") {
+            return Promise.resolve(EMAIL_MAILBOX_MODULE);
+        }
         if (source.sourceType !== "remote_source") {
             throw new Error(`unsupported source type for remote module: ${source.sourceType}`);
         }
@@ -86,6 +90,9 @@ function builtInModuleIdForSourceType(sourceType) {
     if (sourceType === "telegram_bot") {
         return "builtin.telegram_bot";
     }
+    if (sourceType === "email_mailbox") {
+        return "builtin.email_mailbox";
+    }
     return null;
 }
 function builtinRemoteSourceTypes() {
@@ -631,6 +638,73 @@ const TELEGRAM_BOT_MODULE = {
         };
     },
 };
+const EMAIL_MAILBOX_MODULE = {
+    id: "builtin.email_mailbox",
+    listDeliveryOperations(input) {
+        return (0, email_1.emailDeliveryOperationsForHandle)(input.handle);
+    },
+    async invokeDeliveryOperation(input) {
+        return (0, email_1.invokeEmailDeliveryOperation)(input.handle, input.operation, input.input, {
+            source: input.source,
+        });
+    },
+    describeCapabilities() {
+        return {
+            sourceKind: "email_mailbox",
+            aliases: ["email_mailbox", "email"],
+            configSchema: [
+                { name: "provider", type: "string", required: true, description: "Email provider: imap, gmail, graph, or jmap." },
+                { name: "uxcAuth", type: "string", required: true, description: "UXC auth profile name holding mailbox credentials." },
+                { name: "endpoint", type: "string", required: false, description: "imap:// or imaps:// endpoint for imap; provider API endpoint otherwise (required for jmap)." },
+                { name: "account", type: "string", required: false, description: "Account alias; defaults to the auth profile username." },
+                { name: "mailbox", type: "string", required: false, description: "Mailbox to watch; defaults to INBOX." },
+                { name: "pollIntervalSecs", type: "number", required: false, description: "Provider poll interval in seconds (min 15, default 60)." },
+                { name: "smtpEndpoint", type: "string", required: false, description: "Default smtp:// endpoint for outbound delivery." },
+                { name: "fromAddress", type: "string", required: false, description: "Default outbound From address." },
+                { name: "addressAllowlist", type: "string[]", required: false, description: "Optional from/to address allowlist." },
+            ],
+            metadataFields: [
+                { name: "provider", type: "string", description: "Email provider." },
+                { name: "account", type: "string", description: "Mailbox account alias." },
+                { name: "mailbox", type: "string", description: "Mailbox name." },
+                { name: "messageId", type: "string|null", description: "RFC Message-ID when present." },
+                { name: "providerMessageId", type: "string|null", description: "Provider-native message id." },
+                { name: "threadId", type: "string|null", description: "Thread reference from References/In-Reply-To headers." },
+                { name: "from", type: "string|null", description: "Normalized sender address." },
+                { name: "fromName", type: "string|null", description: "Sender display name." },
+                { name: "to", type: "object[]", description: "Normalized recipients." },
+                { name: "cc", type: "object[]", description: "Normalized cc recipients." },
+                { name: "subject", type: "string|null", description: "Message subject." },
+                { name: "textPreview", type: "string|null", description: "Body snippet." },
+                { name: "hasAttachments", type: "boolean", description: "Whether the message carries attachments." },
+                { name: "attachmentCount", type: "number|null", description: "Attachment count; null when provider metadata was not expanded." },
+                { name: "attachments", type: "object[]", description: "Attachment metadata with opaque retrieval handles." },
+            ],
+            eventVariantExamples: ["email.message.received"],
+        };
+    },
+    validateConfig(source) {
+        (0, email_1.parseEmailMailboxSourceConfig)(source);
+    },
+    buildManagedSourceSpec(source) {
+        return (0, email_1.buildEmailMailboxSourceSpec)((0, email_1.parseEmailMailboxSourceConfig)(source));
+    },
+    mapRawEvent(rawPayload, source) {
+        const config = (0, email_1.parseEmailMailboxSourceConfig)(source);
+        const normalized = (0, email_1.normalizeEmailMailboxEvent)(source, config, rawPayload);
+        if (!normalized) {
+            return null;
+        }
+        return {
+            sourceNativeId: normalized.sourceNativeId,
+            eventVariant: normalized.eventVariant,
+            metadata: normalized.metadata ?? {},
+            rawPayload: normalized.rawPayload ?? rawPayload,
+            occurredAt: normalized.occurredAt,
+            deliveryHandle: normalized.deliveryHandle,
+        };
+    },
+};
 function moduleConfigForSource(source) {
     const config = asRecord(source.config);
     if (source.sourceType === "remote_source") {

package/dist/src/store.js

@@ -40,24 +40,29 @@ class AgentInboxStore {
         node_fs_1.default.mkdirSync(node_path_1.default.dirname(dbPath), { recursive: true });
         removeOrphanBackupTmps(dbPath);
         const existedBeforeOpen = node_fs_1.default.existsSync(dbPath);
-        let db = await this.openDatabaseWithRecovery(dbPath);
+        // Legacy AGENTINBOX_STARTUP_BACKUP=1 mode pays for a full check and an
+        // unconditional backup on every open, matching v1.5.2 behavior.
+        const legacyStartupBackup = legacyStartupBackupEnabled(env);
+        let db = await this.openDatabaseWithRecovery(dbPath, legacyStartupBackup);
         let store = new AgentInboxStore(dbPath, db);
+        let archivedPreV1 = false;
         if (existedBeforeOpen && store.shouldArchivePreV1Database()) {
             const archivedPath = store.archivePreV1Database();
             console.warn(`[agentinbox] archived pre-v1 local database to ${archivedPath}; starting with a fresh v1 database (no data imported).`);
             db = this.openDatabase(dbPath);
             store = new AgentInboxStore(dbPath, db);
+            archivedPreV1 = true;
         }
-        else if (existedBeforeOpen && startupBackupEnabled(env)) {
-            await store.backupHealthyDatabase();
+        else if (existedBeforeOpen && legacyStartupBackup) {
+            await store.backupDatabase();
         }
-        store.migrate();
+        await store.migrate({ existedBeforeOpen: existedBeforeOpen && !archivedPreV1, env });
         store.persist();
         return store;
     }
-    static async openDatabaseWithRecovery(dbPath) {
+    static async openDatabaseWithRecovery(dbPath, fullCheck) {
         try {
-            return this.openDatabase(dbPath);
+            return this.openDatabase(dbPath, fullCheck);
         }
         catch (error) {
             if (!node_fs_1.default.existsSync(dbPath)) {
@@ -71,19 +76,29 @@ class AgentInboxStore {
             node_fs_1.default.renameSync(dbPath, corruptPath);
             node_fs_1.default.copyFileSync(backupPath, dbPath);
             console.warn(`[agentinbox] recovered local database from ${backupPath}; archived corrupt database to ${corruptPath}.`);
-            return this.openDatabase(dbPath);
+            return this.openDatabase(dbPath, fullCheck);
         }
     }
-    static openDatabase(dbPath) {
+    static openDatabase(dbPath, fullCheck = false) {
         const db = new better_sqlite3_1.default(dbPath);
         db.pragma("busy_timeout = 5000");
         db.pragma("journal_mode = WAL");
         db.pragma("synchronous = NORMAL");
         db.pragma("foreign_keys = ON");
-        this.assertHealthy(db, dbPath);
+        this.assertHealthy(db, dbPath, fullCheck);
         return db;
     }
-    static assertHealthy(db, dbPath) {
+    /**
+     * Verifies database integrity. Regular opens run `quick_check` and only
+     * escalate to a full `integrity_check` when the quick pass fails, so large
+     * databases do not pay a full scan on every startup. Conservative callers
+     * (legacy `AGENTINBOX_STARTUP_BACKUP=1` mode, recovery-candidate
+     * validation) pass `fullCheck`.
+     */
+    static assertHealthy(db, dbPath, fullCheck) {
+        if (!fullCheck && db.pragma("quick_check", { simple: true }) === "ok") {
+            return;
+        }
         const result = db.pragma("integrity_check", { simple: true });
         if (result !== "ok") {
             db.close();
@@ -95,7 +110,7 @@ class AgentInboxStore {
         for (const candidate of candidates) {
             try {
                 const db = new better_sqlite3_1.default(candidate, { readonly: true, fileMustExist: true });
-                this.assertHealthy(db, candidate);
+                this.assertHealthy(db, candidate, true);
                 db.close();
                 return candidate;
             }
@@ -108,14 +123,32 @@ class AgentInboxStore {
     static listBackupCandidates(dbPath) {
         const dir = node_path_1.default.dirname(dbPath);
         const baseName = node_path_1.default.basename(dbPath);
-        const startupBackups = node_fs_1.default.existsSync(dir)
-            ? node_fs_1.default.readdirSync(dir)
-                .filter((name) => name.startsWith(`${baseName}.startup.`) && name.endsWith(".bak"))
-                .sort()
-                .reverse()
-                .map((name) => node_path_1.default.join(dir, name))
-            : [];
-        return [`${dbPath}.bak`, ...startupBackups].filter((candidate, index, all) => node_fs_1.default.existsSync(candidate) && all.indexOf(candidate) === index);
+        const preMigrationPattern = new RegExp(`^${escapeRegExp(baseName)}\\.pre-migrate-v(\\d+)\\.bak$`);
+        let entries;
+        try {
+            entries = node_fs_1.default.readdirSync(dir);
+        }
+        catch {
+            return [];
+        }
+        const candidates = [];
+        for (const name of entries) {
+            const candidatePath = node_path_1.default.join(dir, name);
+            if (name === `${baseName}.bak`) {
+                candidates.push({ path: candidatePath, version: 0, modifiedAtMs: backupMtimeMs(candidatePath) });
+                continue;
+            }
+            const preMigration = preMigrationPattern.exec(name);
+            if (preMigration) {
+                candidates.push({
+                    path: candidatePath,
+                    version: Number.parseInt(preMigration[1], 10),
+                    modifiedAtMs: backupMtimeMs(candidatePath),
+                });
+            }
+        }
+        candidates.sort((left, right) => right.modifiedAtMs - left.modifiedAtMs || right.version - left.version);
+        return candidates.map((candidate) => candidate.path);
     }
     static nextPath(base) {
         if (!node_fs_1.default.existsSync(base)) {
@@ -135,13 +168,22 @@ class AgentInboxStore {
     }
     getDatabaseHealth() {
         return {
-            integrityCheck: String(this.db.pragma("integrity_check", { simple: true })),
+            quickCheck: String(this.db.pragma("quick_check", { simple: true })),
             journalMode: String(this.db.pragma("journal_mode", { simple: true })),
             foreignKeys: Number(this.db.pragma("foreign_keys", { simple: true })) === 1,
         };
     }
-    async backupHealthyDatabase() {
+    /**
+     * Writes a snapshot to `<db>.bak`, used by `agentinbox backup` and by the
+     * opt-in legacy `AGENTINBOX_STARTUP_BACKUP=1` startup backup. The open-time
+     * health check has already run against this handle. Returns the backup path.
+     */
+    async backupDatabase() {
         const backupPath = `${this.dbPath}.bak`;
+        await this.writeBackupTo(backupPath);
+        return backupPath;
+    }
+    async writeBackupTo(backupPath) {
         const tmpPath = `${backupPath}.${process.pid}.tmp`;
         try {
             node_fs_1.default.rmSync(tmpPath, { force: true });
@@ -152,17 +194,57 @@ class AgentInboxStore {
             node_fs_1.default.rmSync(tmpPath, { force: true });
         }
     }
-    migrate() {
+    async migrate(options) {
         const migrations = this.loadSqlMigrations();
         this.ensureDrizzleMigrationsTable();
         const applied = this.listAppliedMigrationTags();
         const pending = migrations.filter((migration) => !applied.has(migration.tag));
+        if (options.existedBeforeOpen && pending.length > 0) {
+            const backupPath = await this.backupBeforeMigration(migrations.length);
+            console.warn(`[agentinbox] pending schema migrations detected; backed up the local database to ${backupPath} before migrating to schema v${migrations.length}.`);
+            this.pruneMigrationBackups(options.env);
+        }
         for (const migration of pending) {
             this.applyMigration(migration);
         }
         this.ensureInboxEntryBackfill();
         this.setUserVersion(migrations.length);
     }
+    async backupBeforeMigration(targetVersion) {
+        const backupPath = `${this.dbPath}.pre-migrate-v${targetVersion}.bak`;
+        await this.writeBackupTo(backupPath);
+        return backupPath;
+    }
+    /**
+     * Keeps only the newest `AGENTINBOX_MIGRATION_BACKUP_KEEP` pre-migration
+     * backups (default 5; values <= 0 keep everything). Migration backups are
+     * rare, so pruning only runs right after a new one is written.
+     */
+    pruneMigrationBackups(env) {
+        const keep = migrationBackupKeep(env);
+        if (keep <= 0) {
+            return;
+        }
+        const dir = node_path_1.default.dirname(this.dbPath);
+        const pattern = new RegExp(`^${escapeRegExp(node_path_1.default.basename(this.dbPath))}\\.pre-migrate-v(\\d+)\\.bak$`);
+        const entries = [];
+        for (const name of node_fs_1.default.readdirSync(dir)) {
+            const match = pattern.exec(name);
+            if (!match) {
+                continue;
+            }
+            entries.push({ path: node_path_1.default.join(dir, name), version: Number.parseInt(match[1], 10) });
+        }
+        entries.sort((left, right) => right.version - left.version);
+        for (const entry of entries.slice(keep)) {
+            try {
+                node_fs_1.default.rmSync(entry.path, { force: true });
+            }
+            catch {
+                // Best-effort pruning.
+            }
+        }
+    }
     loadSqlMigrations() {
         const migrationsDir = this.resolveMigrationsDir();
         const files = node_fs_1.default
@@ -2384,16 +2466,37 @@ function uniqueSorted(values) {
 function summarizeBackfilledItemEntry(item) {
     return `${item.eventVariant} from ${item.sourceId}`;
 }
-function startupBackupEnabled(env) {
-    return !(0, util_1.isEnvFlagDisabled)(env.AGENTINBOX_STARTUP_BACKUP);
+const DEFAULT_MIGRATION_BACKUP_KEEP = 5;
+/**
+ * Backups are event-driven: a full database backup is taken only before
+ * pending schema migrations run, plus explicit `agentinbox backup` snapshots.
+ * Setting `AGENTINBOX_STARTUP_BACKUP=1` opts back into the legacy v1.5.2
+ * behavior of an unconditional backup and a full `integrity_check` on every
+ * open.
+ */
+function legacyStartupBackupEnabled(env) {
+    return (0, util_1.isEnvFlagEnabled)(env.AGENTINBOX_STARTUP_BACKUP);
+}
+function migrationBackupKeep(env) {
+    const parsed = Number.parseInt(env.AGENTINBOX_MIGRATION_BACKUP_KEEP ?? "", 10);
+    return Number.isInteger(parsed) ? parsed : DEFAULT_MIGRATION_BACKUP_KEEP;
+}
+function backupMtimeMs(candidatePath) {
+    try {
+        return node_fs_1.default.statSync(candidatePath).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
 }
 /**
- * Removes leftover `<db>.bak.<pid>.tmp` files whose owning process is dead.
- * Tmp files owned by a live pid belong to a concurrent open and are preserved.
+ * Removes leftover `<db>.*.bak.<pid>.tmp` files (manual and pre-migration
+ * backup temporaries) whose owning process is dead. Tmp files owned by a live
+ * pid belong to a concurrent open and are preserved.
  */
 function removeOrphanBackupTmps(dbPath) {
     const dir = node_path_1.default.dirname(dbPath);
-    const pattern = new RegExp(`^${escapeRegExp(node_path_1.default.basename(dbPath))}\\.bak\\.(\\d+)\\.tmp$`);
+    const pattern = new RegExp(`^${escapeRegExp(node_path_1.default.basename(dbPath))}\\.(?:.+\\.)?bak\\.(\\d+)\\.tmp$`);
     let entries;
     try {
         entries = node_fs_1.default.readdirSync(dir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holon-run/agentinbox",
-  "version": "1.5.2",
+  "version": "1.7.0",
   "description": "Local event subscription and delivery service for agents.",
   "license": "Apache-2.0",
   "repository": {