larkin 0.4.13 → 0.4.14

package/dist/agent/host-reminder-orchestrator.cjs

@@ -105,25 +105,150 @@ class HostReminderOrchestrator {
     }
     deliver(agent, reminder, overdueMs) {
         const recurrence = reminder.repeat ? this.store.parseRepeat(reminder.repeat, reminder.tz) : null;
-        const envelope = withCanonicalTarget(this.options.envelopeProjector.createReminderEnvelope(agent.agentId, {
+        const projected = this.options.envelopeProjector.createReminderEnvelope(agent.agentId, {
             reminderId: reminder.reminderId,
             title: reminder.title,
             repeat: reminder.repeat ? String(reminder.repeat) : null,
             fireAt: reminder.fireAt,
             msgRef: reminder.msgRef,
             channel: reminder.channel ? String(reminder.channel) : null,
-        }, overdueMs, reminder.repeat && recurrence && !("error" in recurrence) ? (recurrence.description || null) : null));
+            deliveryTarget: reminder.deliveryTarget ?? null,
+            deliveryAnchor: reminder.deliveryAnchor ?? null,
+        }, overdueMs, reminder.repeat && recurrence && !("error" in recurrence) ? (recurrence.description || null) : null);
+        const envelope = withCanonicalTarget({ ...projected,
+            // The projector also derives safe routing for pre-0.4.14 records; do not
+            // overwrite that migration result with the absent fields from the record.
+            deliveryTarget: reminder.deliveryTarget ?? projected.deliveryTarget ?? null,
+            deliveryAnchor: reminder.deliveryAnchor ?? projected.deliveryAnchor ?? null });
+        const auditableDelivery = typeof envelope.deliveryTarget === "string" && envelope.deliveryTarget.length > 0;
+        // Persist the pending audit marker before the Inbox row becomes pollable.
+        // An already-active Agent can poll and answer the wake immediately, and
+        // RuntimeHost.deliver may execute the whole turn before its promise settles
+        // (notably with Pi); without a durable pending marker that outbound write
+        // would be invisible to the audit. Internal/no-delivery reminders still
+        // wake the Runtime, but have no user-facing delivery to audit.
+        if (auditableDelivery && !this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_pending", {
+            outcome: "awaiting_runtime", deliveryTarget: envelope.deliveryTarget, occurrenceId: envelope.message_id,
+        })) {
+            this.log(`reminder delivery pending 审计写失败 id=#${reminder.reminderId.slice(0, 8)}（拒绝唤醒）`);
+            return;
+        }
+        let stateStore;
+        let deliveryAnchorBound = false;
         try {
-            this.options.stateStore(agent).appendNdjson("inbox", envelope);
+            stateStore = this.options.stateStore(agent);
+            if (envelope.deliveryTarget && envelope.deliveryAnchor) {
+                stateStore.bindInboxDeliveryAnchor(envelope.deliveryAnchor, envelope.deliveryTarget);
+                deliveryAnchorBound = true;
+            }
+            stateStore.appendNdjson("inbox", envelope);
         }
         catch (error) {
+            if (deliveryAnchorBound && stateStore?.unbindInboxDeliveryAnchor && envelope.deliveryTarget && envelope.deliveryAnchor) {
+                try {
+                    stateStore.unbindInboxDeliveryAnchor(envelope.deliveryAnchor, envelope.deliveryTarget);
+                }
+                catch (rollbackError) {
+                    this.log("reminder Inbox anchor 回滚失败", rollbackError.message);
+                }
+            }
             this.log("reminder inbox 写失败", error.message);
+            // The wake row never became durable, so the pending marker must not stay
+            // open awaiting a Runtime turn that can never poll this occurrence.
+            if (auditableDelivery) {
+                this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_failed", {
+                    outcome: "inbox_write_failed", reason: String(error.message || error),
+                    deliveryTarget: envelope.deliveryTarget, occurrenceId: envelope.message_id,
+                });
+            }
             return;
         }
-        if (this.options.deliveryTarget)
-            void this.options.deliveryTarget.deliver(agent.agentId, envelope);
-        else
+        if (!this.options.deliveryTarget) {
             this.log(`reminder 触发但 Runtime Host 未就绪 id=#${reminder.reminderId.slice(0, 8)}（仅入 inbox）`);
+            if (auditableDelivery) {
+                this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_failed", {
+                    outcome: "runtime_unavailable", occurrenceId: envelope.message_id,
+                });
+            }
+            return;
+        }
+        try {
+            const recordReceipt = (receipt) => {
+                if (!auditableDelivery)
+                    return;
+                const status = receipt && typeof receipt === "object" ? String(receipt.status || "") : "";
+                const reason = receipt && typeof receipt === "object" ? String(receipt.reason || "") : "";
+                // RuntimeHost.deliver only acknowledges Inbox persistence/wake submission.
+                // It does not prove that the Agent later committed an outbound Feishu
+                // message, so accepted, duplicate, and an empty receipt remain pending.
+                if (!status || status === "accepted" || status === "duplicate") {
+                    this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_pending", {
+                        outcome: status || "empty", deliveryTarget: envelope.deliveryTarget, occurrenceId: envelope.message_id,
+                    });
+                }
+                else if (status === "deferred") {
+                    this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_pending", {
+                        outcome: "deferred", ...(reason ? { reason } : {}), deliveryTarget: envelope.deliveryTarget, occurrenceId: envelope.message_id,
+                    });
+                }
+                else {
+                    this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_failed", {
+                        outcome: "error", ...(reason ? { reason } : {}), deliveryTarget: envelope.deliveryTarget, occurrenceId: envelope.message_id,
+                    });
+                }
+            };
+            const result = this.options.deliveryTarget.deliver(agent.agentId, envelope);
+            if (result && typeof result.then === "function") {
+                void Promise.resolve(result).then(recordReceipt, (error) => this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_failed", {
+                    outcome: "rejected", reason: String(error?.message || error), deliveryTarget: envelope.deliveryTarget, occurrenceId: envelope.message_id,
+                }));
+            }
+            else {
+                recordReceipt(result);
+            }
+        }
+        catch (error) {
+            if (typeof envelope.deliveryTarget === "string" && envelope.deliveryTarget.length > 0) {
+                this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_failed", {
+                    outcome: "rejected", reason: String(error.message || error), deliveryTarget: envelope.deliveryTarget,
+                    occurrenceId: envelope.message_id,
+                });
+            }
+            this.log(`reminder delivery 失败 id=#${reminder.reminderId.slice(0, 8)}: ${error.message}`);
+        }
+    }
+    recordDeliveryOutcome(agent, reminderId, eventType, metadata) {
+        try {
+            return this.store.mutate(this.options.stateStore(agent).paths.reminders, (store) => {
+                const reminder = store.reminders.find((candidate) => candidate.reminderId === reminderId);
+                if (!reminder)
+                    return false;
+                const occurrenceId = typeof metadata.occurrenceId === "string" ? metadata.occurrenceId : null;
+                const occurrenceEvents = occurrenceId
+                    ? reminder.events?.filter((event) => event.metadata?.occurrenceId === occurrenceId)
+                    : undefined;
+                const hasOccurrenceMetadata = reminder.events?.some((event) => typeof event.metadata?.occurrenceId === "string");
+                const last = occurrenceId
+                    ? (occurrenceEvents?.at(-1) ?? (hasOccurrenceMetadata && reminder.events?.at(-1)?.eventType !== "fired"
+                        ? undefined : reminder.events?.at(-1)))
+                    : reminder.events?.at(-1);
+                if (!last || !["fired", "delivery_pending", "delivery_failed"].includes(last.eventType))
+                    return false;
+                // A late Runtime receipt must not resurrect an occurrence finalized as failed.
+                if (eventType === "delivery_pending" && last.eventType === "delivery_failed")
+                    return false;
+                // A synchronous outbound can finish inside deliveryTarget.deliver().
+                // Never let its later Runtime receipt callback downgrade that success.
+                if (eventType !== "delivery_succeeded" && last.eventType === "delivery_succeeded")
+                    return false;
+                this.store.appendEvent(reminder, eventType, "system", null, reminder.status === "scheduled" ? reminder.fireAt : null, this.now(), metadata);
+                return true;
+            });
+        }
+        catch (error) {
+            this.log(`reminder delivery audit 写失败 id=#${reminderId.slice(0, 8)}: ${error.message}`);
+            return false;
+        }
     }
     handleFire(message) {
         const agent = this.options.agents.find((candidate) => candidate.agentId === message.agentId);
@@ -163,7 +288,9 @@ class HostReminderOrchestrator {
                     reminder.firedAt = this.store.nowIso(now);
                 }
                 reminder.version = Number(reminder.version) + 1;
-                this.store.appendEvent(reminder, "fired", "system", null, reminder.status === "scheduled" ? reminder.fireAt : null, now);
+                this.store.appendEvent(reminder, "fired", "system", null, reminder.status === "scheduled" ? reminder.fireAt : null, now, {
+                    deliveryTarget: reminder.deliveryTarget ?? null, deliveryAnchor: reminder.deliveryAnchor ?? null,
+                });
                 store.reminders = store.reminders.filter((candidate) => candidate.status === "scheduled" || now - Date.parse(candidate.firedAt || candidate.createdAt || "") < 30 * 86_400_000);
                 action = "deliver";
                 fired = { ...reminder };

package/dist/agent/host-reminder-orchestrator.mjs

@@ -69,25 +69,150 @@ export class HostReminderOrchestrator {
     }
     deliver(agent, reminder, overdueMs) {
         const recurrence = reminder.repeat ? this.store.parseRepeat(reminder.repeat, reminder.tz) : null;
-        const envelope = withCanonicalTarget(this.options.envelopeProjector.createReminderEnvelope(agent.agentId, {
+        const projected = this.options.envelopeProjector.createReminderEnvelope(agent.agentId, {
             reminderId: reminder.reminderId,
             title: reminder.title,
             repeat: reminder.repeat ? String(reminder.repeat) : null,
             fireAt: reminder.fireAt,
             msgRef: reminder.msgRef,
             channel: reminder.channel ? String(reminder.channel) : null,
-        }, overdueMs, reminder.repeat && recurrence && !("error" in recurrence) ? (recurrence.description || null) : null));
+            deliveryTarget: reminder.deliveryTarget ?? null,
+            deliveryAnchor: reminder.deliveryAnchor ?? null,
+        }, overdueMs, reminder.repeat && recurrence && !("error" in recurrence) ? (recurrence.description || null) : null);
+        const envelope = withCanonicalTarget({ ...projected,
+            // The projector also derives safe routing for pre-0.4.14 records; do not
+            // overwrite that migration result with the absent fields from the record.
+            deliveryTarget: reminder.deliveryTarget ?? projected.deliveryTarget ?? null,
+            deliveryAnchor: reminder.deliveryAnchor ?? projected.deliveryAnchor ?? null });
+        const auditableDelivery = typeof envelope.deliveryTarget === "string" && envelope.deliveryTarget.length > 0;
+        // Persist the pending audit marker before the Inbox row becomes pollable.
+        // An already-active Agent can poll and answer the wake immediately, and
+        // RuntimeHost.deliver may execute the whole turn before its promise settles
+        // (notably with Pi); without a durable pending marker that outbound write
+        // would be invisible to the audit. Internal/no-delivery reminders still
+        // wake the Runtime, but have no user-facing delivery to audit.
+        if (auditableDelivery && !this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_pending", {
+            outcome: "awaiting_runtime", deliveryTarget: envelope.deliveryTarget, occurrenceId: envelope.message_id,
+        })) {
+            this.log(`reminder delivery pending 审计写失败 id=#${reminder.reminderId.slice(0, 8)}（拒绝唤醒）`);
+            return;
+        }
+        let stateStore;
+        let deliveryAnchorBound = false;
         try {
-            this.options.stateStore(agent).appendNdjson("inbox", envelope);
+            stateStore = this.options.stateStore(agent);
+            if (envelope.deliveryTarget && envelope.deliveryAnchor) {
+                stateStore.bindInboxDeliveryAnchor(envelope.deliveryAnchor, envelope.deliveryTarget);
+                deliveryAnchorBound = true;
+            }
+            stateStore.appendNdjson("inbox", envelope);
         }
         catch (error) {
+            if (deliveryAnchorBound && stateStore?.unbindInboxDeliveryAnchor && envelope.deliveryTarget && envelope.deliveryAnchor) {
+                try {
+                    stateStore.unbindInboxDeliveryAnchor(envelope.deliveryAnchor, envelope.deliveryTarget);
+                }
+                catch (rollbackError) {
+                    this.log("reminder Inbox anchor 回滚失败", rollbackError.message);
+                }
+            }
             this.log("reminder inbox 写失败", error.message);
+            // The wake row never became durable, so the pending marker must not stay
+            // open awaiting a Runtime turn that can never poll this occurrence.
+            if (auditableDelivery) {
+                this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_failed", {
+                    outcome: "inbox_write_failed", reason: String(error.message || error),
+                    deliveryTarget: envelope.deliveryTarget, occurrenceId: envelope.message_id,
+                });
+            }
             return;
         }
-        if (this.options.deliveryTarget)
-            void this.options.deliveryTarget.deliver(agent.agentId, envelope);
-        else
+        if (!this.options.deliveryTarget) {
             this.log(`reminder 触发但 Runtime Host 未就绪 id=#${reminder.reminderId.slice(0, 8)}（仅入 inbox）`);
+            if (auditableDelivery) {
+                this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_failed", {
+                    outcome: "runtime_unavailable", occurrenceId: envelope.message_id,
+                });
+            }
+            return;
+        }
+        try {
+            const recordReceipt = (receipt) => {
+                if (!auditableDelivery)
+                    return;
+                const status = receipt && typeof receipt === "object" ? String(receipt.status || "") : "";
+                const reason = receipt && typeof receipt === "object" ? String(receipt.reason || "") : "";
+                // RuntimeHost.deliver only acknowledges Inbox persistence/wake submission.
+                // It does not prove that the Agent later committed an outbound Feishu
+                // message, so accepted, duplicate, and an empty receipt remain pending.
+                if (!status || status === "accepted" || status === "duplicate") {
+                    this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_pending", {
+                        outcome: status || "empty", deliveryTarget: envelope.deliveryTarget, occurrenceId: envelope.message_id,
+                    });
+                }
+                else if (status === "deferred") {
+                    this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_pending", {
+                        outcome: "deferred", ...(reason ? { reason } : {}), deliveryTarget: envelope.deliveryTarget, occurrenceId: envelope.message_id,
+                    });
+                }
+                else {
+                    this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_failed", {
+                        outcome: "error", ...(reason ? { reason } : {}), deliveryTarget: envelope.deliveryTarget, occurrenceId: envelope.message_id,
+                    });
+                }
+            };
+            const result = this.options.deliveryTarget.deliver(agent.agentId, envelope);
+            if (result && typeof result.then === "function") {
+                void Promise.resolve(result).then(recordReceipt, (error) => this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_failed", {
+                    outcome: "rejected", reason: String(error?.message || error), deliveryTarget: envelope.deliveryTarget, occurrenceId: envelope.message_id,
+                }));
+            }
+            else {
+                recordReceipt(result);
+            }
+        }
+        catch (error) {
+            if (typeof envelope.deliveryTarget === "string" && envelope.deliveryTarget.length > 0) {
+                this.recordDeliveryOutcome(agent, reminder.reminderId, "delivery_failed", {
+                    outcome: "rejected", reason: String(error.message || error), deliveryTarget: envelope.deliveryTarget,
+                    occurrenceId: envelope.message_id,
+                });
+            }
+            this.log(`reminder delivery 失败 id=#${reminder.reminderId.slice(0, 8)}: ${error.message}`);
+        }
+    }
+    recordDeliveryOutcome(agent, reminderId, eventType, metadata) {
+        try {
+            return this.store.mutate(this.options.stateStore(agent).paths.reminders, (store) => {
+                const reminder = store.reminders.find((candidate) => candidate.reminderId === reminderId);
+                if (!reminder)
+                    return false;
+                const occurrenceId = typeof metadata.occurrenceId === "string" ? metadata.occurrenceId : null;
+                const occurrenceEvents = occurrenceId
+                    ? reminder.events?.filter((event) => event.metadata?.occurrenceId === occurrenceId)
+                    : undefined;
+                const hasOccurrenceMetadata = reminder.events?.some((event) => typeof event.metadata?.occurrenceId === "string");
+                const last = occurrenceId
+                    ? (occurrenceEvents?.at(-1) ?? (hasOccurrenceMetadata && reminder.events?.at(-1)?.eventType !== "fired"
+                        ? undefined : reminder.events?.at(-1)))
+                    : reminder.events?.at(-1);
+                if (!last || !["fired", "delivery_pending", "delivery_failed"].includes(last.eventType))
+                    return false;
+                // A late Runtime receipt must not resurrect an occurrence finalized as failed.
+                if (eventType === "delivery_pending" && last.eventType === "delivery_failed")
+                    return false;
+                // A synchronous outbound can finish inside deliveryTarget.deliver().
+                // Never let its later Runtime receipt callback downgrade that success.
+                if (eventType !== "delivery_succeeded" && last.eventType === "delivery_succeeded")
+                    return false;
+                this.store.appendEvent(reminder, eventType, "system", null, reminder.status === "scheduled" ? reminder.fireAt : null, this.now(), metadata);
+                return true;
+            });
+        }
+        catch (error) {
+            this.log(`reminder delivery audit 写失败 id=#${reminderId.slice(0, 8)}: ${error.message}`);
+            return false;
+        }
     }
     handleFire(message) {
         const agent = this.options.agents.find((candidate) => candidate.agentId === message.agentId);
@@ -127,7 +252,9 @@ export class HostReminderOrchestrator {
                     reminder.firedAt = this.store.nowIso(now);
                 }
                 reminder.version = Number(reminder.version) + 1;
-                this.store.appendEvent(reminder, "fired", "system", null, reminder.status === "scheduled" ? reminder.fireAt : null, now);
+                this.store.appendEvent(reminder, "fired", "system", null, reminder.status === "scheduled" ? reminder.fireAt : null, now, {
+                    deliveryTarget: reminder.deliveryTarget ?? null, deliveryAnchor: reminder.deliveryAnchor ?? null,
+                });
                 store.reminders = store.reminders.filter((candidate) => candidate.status === "scheduled" || now - Date.parse(candidate.firedAt || candidate.createdAt || "") < 30 * 86_400_000);
                 action = "deliver";
                 fired = { ...reminder };

package/dist/agent/inbox-projection.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RUNTIME_REDELIVERY_TARGET = exports.RUNTIME_REMINDER_TARGET = void 0;
 exports.isCanonicalInboxTarget = isCanonicalInboxTarget;
+exports.isUserDeliveryTarget = isUserDeliveryTarget;
 exports.targetKeyOfInboxEnvelope = targetKeyOfInboxEnvelope;
 exports.projectInboxEnvelope = projectInboxEnvelope;
 exports.targetOfInboxEnvelope = targetOfInboxEnvelope;
@@ -50,6 +51,10 @@ function isCanonicalInboxTarget(target) {
         || target === exports.RUNTIME_REDELIVERY_TARGET
         || isDocumentCommentTarget(target);
 }
+/** Targets that can safely receive a user-facing reminder. Runtime wake targets are not delivery destinations. */
+function isUserDeliveryTarget(target) {
+    return isChatTarget(target) || isThreadTarget(target) || isDocumentCommentTarget(target);
+}
 function invalidTarget(target) {
     return new Error(`Invalid canonical Inbox target ${JSON.stringify(target)}; expected chat:<nonempty>, thread:<nonempty>, runtime:reminder, runtime:redelivery, or document-comment:<nonempty>`);
 }

package/dist/agent/inbox-projection.mjs

@@ -41,6 +41,10 @@ export function isCanonicalInboxTarget(target) {
         || target === RUNTIME_REDELIVERY_TARGET
         || isDocumentCommentTarget(target);
 }
+/** Targets that can safely receive a user-facing reminder. Runtime wake targets are not delivery destinations. */
+export function isUserDeliveryTarget(target) {
+    return isChatTarget(target) || isThreadTarget(target) || isDocumentCommentTarget(target);
+}
 function invalidTarget(target) {
     return new Error(`Invalid canonical Inbox target ${JSON.stringify(target)}; expected chat:<nonempty>, thread:<nonempty>, runtime:reminder, runtime:redelivery, or document-comment:<nonempty>`);
 }

package/dist/agent/reminder-delivery-audit.cjs

@@ -0,0 +1,86 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.auditReminderDelivery = auditReminderDelivery;
+const ReminderStore = __importStar(require("./reminder-store.cjs"));
+/** Record only committed, non-dry-run outbound attempts for the consumed reminder. */
+function auditReminderDelivery(input) {
+    if (input.dryRun)
+        return;
+    const current = (input.stateStore.resolveCurrentReminders?.() ?? [input.stateStore.resolveCurrentReminder()]).filter((candidate) => Boolean(candidate)).find((candidate) => {
+        if (input.reminderId && candidate.reminderId !== input.reminderId)
+            return false;
+        if (input.deliveryAnchor && candidate.deliveryAnchor !== input.deliveryAnchor)
+            return false;
+        const currentChatId = candidate.deliveryTarget.match(/^chat:(oc_[A-Za-z0-9_-]+)$/)?.[1];
+        const outboundChatId = currentChatId && input.resolveChatId ? input.resolveChatId(input.target) : null;
+        return candidate.deliveryTarget === input.target || outboundChatId === currentChatId;
+    });
+    if (!current)
+        return;
+    // Match events against the consumed occurrence even when the outbound did
+    // not name one: a snooze/update/cancel appended after polling must not hide
+    // the pending occurrence that this committed write actually fulfilled.
+    const anchor = input.deliveryAnchor || current.deliveryAnchor;
+    let persisted = false;
+    ReminderStore.mutate(input.stateStore.paths.reminders, (store) => {
+        const reminder = store.reminders.find((candidate) => candidate.reminderId === current.reminderId);
+        const occurrenceEvents = anchor
+            ? reminder?.events?.filter((event) => event.metadata?.occurrenceId === anchor)
+            : undefined;
+        const hasOccurrenceMetadata = reminder?.events?.some((event) => typeof event.metadata?.occurrenceId === "string");
+        const last = anchor
+            ? (occurrenceEvents?.at(-1) ?? (hasOccurrenceMetadata ? undefined : reminder?.events?.at(-1)))
+            : reminder?.events?.at(-1);
+        if (!reminder || !last || !["delivery_pending", "delivery_failed"].includes(last.eventType))
+            return;
+        if (input.finalize && !input.succeeded && last.eventType === "delivery_failed")
+            return;
+        if (!input.succeeded && last.eventType === "delivery_failed")
+            return;
+        ReminderStore.appendEvent(reminder, input.succeeded ? "delivery_succeeded" : "delivery_failed", "agent", input.agentId, reminder.status === "scheduled" ? reminder.fireAt : null, Date.now(), {
+            deliveryTarget: input.target,
+            occurrenceId: current.deliveryAnchor,
+            ...((input.messageId || current.deliveryMessageId) ? { messageId: input.messageId || current.deliveryMessageId } : {}),
+            ...(input.reason ? { reason: input.reason } : {}),
+        });
+        persisted = true;
+    });
+    // Clear only after delivery_succeeded was durably appended; otherwise keep
+    // the occurrence context so a later reconciliation can still record the
+    // committed write instead of silently dropping its audit trail.
+    if (input.succeeded && persisted)
+        input.stateStore.clearCurrentReminder(current.reminderId, current.deliveryAnchor);
+}

package/dist/agent/reminder-delivery-audit.mjs

@@ -0,0 +1,50 @@
+import * as ReminderStore from "./reminder-store.mjs";
+/** Record only committed, non-dry-run outbound attempts for the consumed reminder. */
+export function auditReminderDelivery(input) {
+    if (input.dryRun)
+        return;
+    const current = (input.stateStore.resolveCurrentReminders?.() ?? [input.stateStore.resolveCurrentReminder()]).filter((candidate) => Boolean(candidate)).find((candidate) => {
+        if (input.reminderId && candidate.reminderId !== input.reminderId)
+            return false;
+        if (input.deliveryAnchor && candidate.deliveryAnchor !== input.deliveryAnchor)
+            return false;
+        const currentChatId = candidate.deliveryTarget.match(/^chat:(oc_[A-Za-z0-9_-]+)$/)?.[1];
+        const outboundChatId = currentChatId && input.resolveChatId ? input.resolveChatId(input.target) : null;
+        return candidate.deliveryTarget === input.target || outboundChatId === currentChatId;
+    });
+    if (!current)
+        return;
+    // Match events against the consumed occurrence even when the outbound did
+    // not name one: a snooze/update/cancel appended after polling must not hide
+    // the pending occurrence that this committed write actually fulfilled.
+    const anchor = input.deliveryAnchor || current.deliveryAnchor;
+    let persisted = false;
+    ReminderStore.mutate(input.stateStore.paths.reminders, (store) => {
+        const reminder = store.reminders.find((candidate) => candidate.reminderId === current.reminderId);
+        const occurrenceEvents = anchor
+            ? reminder?.events?.filter((event) => event.metadata?.occurrenceId === anchor)
+            : undefined;
+        const hasOccurrenceMetadata = reminder?.events?.some((event) => typeof event.metadata?.occurrenceId === "string");
+        const last = anchor
+            ? (occurrenceEvents?.at(-1) ?? (hasOccurrenceMetadata ? undefined : reminder?.events?.at(-1)))
+            : reminder?.events?.at(-1);
+        if (!reminder || !last || !["delivery_pending", "delivery_failed"].includes(last.eventType))
+            return;
+        if (input.finalize && !input.succeeded && last.eventType === "delivery_failed")
+            return;
+        if (!input.succeeded && last.eventType === "delivery_failed")
+            return;
+        ReminderStore.appendEvent(reminder, input.succeeded ? "delivery_succeeded" : "delivery_failed", "agent", input.agentId, reminder.status === "scheduled" ? reminder.fireAt : null, Date.now(), {
+            deliveryTarget: input.target,
+            occurrenceId: current.deliveryAnchor,
+            ...((input.messageId || current.deliveryMessageId) ? { messageId: input.messageId || current.deliveryMessageId } : {}),
+            ...(input.reason ? { reason: input.reason } : {}),
+        });
+        persisted = true;
+    });
+    // Clear only after delivery_succeeded was durably appended; otherwise keep
+    // the occurrence context so a later reconciliation can still record the
+    // committed write instead of silently dropping its audit trail.
+    if (input.succeeded && persisted)
+        input.stateStore.clearCurrentReminder(current.reminderId, current.deliveryAnchor);
+}

package/dist/agent/reminder-routes.cjs

@@ -35,9 +35,32 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createReminderRoutes = createReminderRoutes;
 const ReminderStore = __importStar(require("./reminder-store.cjs"));
+const inbox_projection_js_1 = require("./inbox-projection.cjs");
 function versionOf(reminder) {
     return Number(reminder.version || 0);
 }
+const VALID_IM_ANCHOR = /^om_[A-Za-z0-9_-]+$/;
+const VALID_COMMENT_ANCHOR = /^doc_comment_[A-Za-z0-9_-]+$/;
+const VALID_CHAT_TARGET = /^chat:oc_[A-Za-z0-9_-]+$/;
+const VALID_THREAD_TARGET = /^thread:oc_[A-Za-z0-9_-]+:omt_[A-Za-z0-9_-]+$/;
+const VALID_DOCUMENT_COMMENT_TARGET = /^document-comment:(doc|docx|sheet|file):[A-Za-z0-9_-]+:[A-Za-z0-9_-]+:(in-thread|top-level)$/;
+function userTarget(value, field) {
+    const raw = String(value ?? "").trim();
+    // --channel historically accepted an oc_ chat id; retain that unambiguous form.
+    const target = /^oc_[A-Za-z0-9_-]+$/.test(raw) ? `chat:${raw}` : raw;
+    const complete = VALID_CHAT_TARGET.test(target) || VALID_THREAD_TARGET.test(target) || VALID_DOCUMENT_COMMENT_TARGET.test(target);
+    if (!complete || !(0, inbox_projection_js_1.isCanonicalInboxTarget)(target) || !(0, inbox_projection_js_1.isUserDeliveryTarget)(target)) {
+        throw new Error(`${field} 必须是完整可投递的 canonical target（chat:oc_<id>、thread:oc_<chat>:omt_<thread> 或完整 document-comment locator）`);
+    }
+    return target;
+}
+function validAnchor(value, field = "message-id", target) {
+    const anchor = String(value ?? "").trim();
+    const valid = VALID_IM_ANCHOR.test(anchor) || (target?.startsWith("document-comment:") === true && VALID_COMMENT_ANCHOR.test(anchor));
+    if (!valid)
+        throw new Error(`${field} 必须是有效的 Feishu om_ message_id，或 document-comment source 的 doc_comment_ anchor`);
+    return anchor;
+}
 function createReminderRoutes(options) {
     const now = options.now ?? Date.now;
     const timeZone = options.timeZone ?? (() => Intl.DateTimeFormat().resolvedOptions().timeZone);
@@ -54,6 +77,60 @@ function createReminderRoutes(options) {
                 return { ok: false, status: 400, error: "title 不能为空" };
             const current = now();
             const tz = typeof body.tz === "string" && body.tz ? body.tz : timeZone();
+            const internal = body.internal === true || body.noDelivery === true;
+            let deliveryTarget = null;
+            let deliveryAnchor = null;
+            if (internal) {
+                if (body.deliveryTarget !== undefined || body.channel !== undefined || body.msgId !== undefined) {
+                    return { ok: false, status: 400, error: "internal/no-delivery reminder 不应携带 user-facing delivery target" };
+                }
+            }
+            else {
+                try {
+                    const hasExplicitTarget = body.deliveryTarget !== undefined && body.deliveryTarget !== null && Boolean(String(body.deliveryTarget).trim());
+                    const hasExplicitChannel = body.channel !== undefined && body.channel !== null && Boolean(String(body.channel).trim());
+                    // deliveryTarget and channel are destination aliases. Preferring one
+                    // over a contradicting other could route to the wrong conversation,
+                    // so a disagreement fails closed instead of being silently resolved.
+                    if (hasExplicitTarget && hasExplicitChannel
+                        && userTarget(body.deliveryTarget, "delivery target") !== userTarget(body.channel, "channel")) {
+                        return { ok: false, status: 400, error: "deliveryTarget 与 channel 指向不同目的地；请只提供其中一个" };
+                    }
+                    const explicit = hasExplicitTarget ? body.deliveryTarget : hasExplicitChannel ? body.channel : undefined;
+                    if (explicit !== undefined)
+                        deliveryTarget = userTarget(explicit, "delivery target");
+                    if (body.msgId !== undefined && body.msgId !== null && String(body.msgId).trim()) {
+                        const anchorTarget = options.resolveMessageTarget?.(String(body.msgId).trim()) || null;
+                        deliveryAnchor = validAnchor(body.msgId, "message-id", anchorTarget || deliveryTarget);
+                        if (deliveryTarget && !anchorTarget) {
+                            return { ok: false, status: 400, error: `message-id ${String(body.msgId).trim()} 无法验证其所属 Inbox target；请省略 anchor 或提供可验证的 anchor` };
+                        }
+                        if (!deliveryTarget && !anchorTarget) {
+                            return { ok: false, status: 400, error: `message-id ${deliveryAnchor} 没有当前 Inbox 的 canonical delivery target` };
+                        }
+                        if (anchorTarget) {
+                            const normalizedAnchorTarget = userTarget(anchorTarget, "message-id target");
+                            if (deliveryTarget && deliveryTarget !== normalizedAnchorTarget) {
+                                return { ok: false, status: 400, error: "delivery target 与 message-id 所属 Inbox target 冲突" };
+                            }
+                            deliveryTarget = deliveryTarget || normalizedAnchorTarget;
+                        }
+                    }
+                    if (deliveryTarget && (deliveryTarget.startsWith("thread:") || deliveryTarget.startsWith("document-comment:")) && !deliveryAnchor) {
+                        return { ok: false, status: 400, error: `${deliveryTarget} 必须同时提供可验证的 message-id anchor` };
+                    }
+                    if (!deliveryTarget) {
+                        const source = options.currentInboxSource?.() || null;
+                        if (!source)
+                            return { ok: false, status: 400, error: "user-facing reminder 必须显式指定 delivery target，或从当前 Inbox source 派生" };
+                        deliveryTarget = userTarget(source.deliveryTarget, "current Inbox target");
+                        deliveryAnchor = validAnchor(source.deliveryAnchor, "current Inbox anchor", deliveryTarget);
+                    }
+                }
+                catch (error) {
+                    return { ok: false, status: 400, error: error.message };
+                }
+            }
             let recurrence = null;
             if (body.repeat !== undefined) {
                 recurrence = ReminderStore.parseRepeat(body.repeat, tz);
@@ -78,14 +155,17 @@ function createReminderRoutes(options) {
             const reminder = {
                 reminderId: ReminderStore.newId(), ownerAgentId: options.agentId, title,
                 fireAt: ReminderStore.nowIso(fireAtMs), firedAt: null, createdAt: ReminderStore.nowIso(current),
-                status: "scheduled", msgRef: body.msgId ?? null, msgPermalink: null,
+                status: "scheduled", msgRef: deliveryAnchor, msgPermalink: null,
+                deliveryTarget, deliveryAnchor, deliveryMode: internal ? "internal" : "user",
                 repeat: body.repeat ?? null, tz: body.repeat !== undefined ? tz : null,
                 channel: body.channel ?? null, payload: body.payload ?? null,
                 version: 1, events: [],
             };
-            ReminderStore.appendEvent(reminder, "scheduled", "agent", options.agentId, reminder.fireAt, current);
+            ReminderStore.appendEvent(reminder, "scheduled", "agent", options.agentId, reminder.fireAt, current, {
+                deliveryTarget, deliveryAnchor, deliveryMode: internal ? "internal" : "user",
+            });
             ReminderStore.mutate(options.stateFile, (store) => store.reminders.push(reminder));
-            options.log(`reminder 已建 #${reminder.reminderId.slice(0, 8)} fireAt=${reminder.fireAt}${reminder.repeat ? ` repeat=${String(reminder.repeat)}` : ""}`);
+            options.log(`reminder 已建 #${reminder.reminderId.slice(0, 8)} fireAt=${reminder.fireAt}${reminder.repeat ? ` repeat=${String(reminder.repeat)}` : ""} deliveryTarget=${deliveryTarget || "none"}`);
             return { ok: true, status: 200, data: { reminder: ReminderStore.toSummary(reminder), ...(warning ? { warning } : {}) } };
         }
         if (method === "GET" && !reminderId) {