@murphai/murph 0.1.15 → 0.1.17

package/node_modules/@murphai/assistant-engine/dist/assistant/outbox.js

@@ -0,0 +1,774 @@
+import { randomUUID } from 'node:crypto';
+import { readdir, readFile, rename } from 'node:fs/promises';
+import path from 'node:path';
+import { assistantChannelDeliverySchema, assistantOutboxIntentSchema, } from '../assistant-cli-contracts.js';
+import { deliverAssistantMessageOverBinding } from '../outbound-channel.js';
+import { maybeThrowInjectedAssistantFault } from './fault-injection.js';
+import { recordAssistantDiagnosticEvent } from './diagnostics.js';
+import { withAssistantRuntimeWriteLock } from './runtime-write-lock.js';
+import { ensureAssistantState } from './store/persistence.js';
+import { resolveAssistantStatePaths, saveAssistantSession } from './store.js';
+import { appendAssistantTurnReceiptEvent, updateAssistantTurnReceipt } from './turns.js';
+import { buildAssistantOutboxPersistedTarget, buildAssistantOutboxRawTargetIdentity, hashAssistantOutboxIdentity, hashAssistantOutboxTargetFingerprint, resolveAssistantOutboxIntentPath, resolveAssistantOutboxQuarantineDirectory, } from './outbox/intents.js';
+import { createAssistantDeliveryConfirmationPendingError, isAssistantOutboxRetryableError, normalizeAssistantDeliveryError, resolveAssistantOutboxRetryDelayMs, shouldBeginAssistantOutboxDispatch, shouldDispatchAssistantOutboxIntent, } from './outbox/retry-policy.js';
+import { ensureAssistantStateDirectory, isMissingFileError, normalizeNullableString, warnAssistantBestEffortFailure, writeJsonFileAtomic, } from './shared.js';
+const ASSISTANT_OUTBOX_INTENT_SCHEMA = 'murph.assistant-outbox-intent.v1';
+export { isAssistantOutboxRetryableError, normalizeAssistantDeliveryError, shouldDispatchAssistantOutboxIntent, };
+export async function createAssistantOutboxIntent(input) {
+    return withAssistantRuntimeWriteLock(input.vault, async (paths) => {
+        await ensureAssistantState(paths);
+        const createdAt = input.createdAt ?? new Date().toISOString();
+        const message = normalizeRequiredMessage(input.message);
+        const rawTargetIdentity = buildAssistantOutboxRawTargetIdentity(input);
+        const dedupeKey = hashAssistantOutboxIdentity({
+            dedupeToken: input.dedupeToken,
+            message,
+            sessionId: input.sessionId,
+            turnId: input.turnId,
+            ...rawTargetIdentity,
+        });
+        const existing = await findAssistantOutboxIntentByDedupeKey(input.vault, dedupeKey);
+        if (existing) {
+            return existing;
+        }
+        const intent = assistantOutboxIntentSchema.parse({
+            schema: ASSISTANT_OUTBOX_INTENT_SCHEMA,
+            intentId: `outbox_${randomUUID().replace(/-/gu, '')}`,
+            sessionId: input.sessionId,
+            turnId: input.turnId,
+            createdAt,
+            updatedAt: createdAt,
+            lastAttemptAt: null,
+            nextAttemptAt: createdAt,
+            sentAt: null,
+            attemptCount: 0,
+            status: 'pending',
+            message,
+            dedupeKey,
+            targetFingerprint: hashAssistantOutboxTargetFingerprint(rawTargetIdentity),
+            ...buildAssistantOutboxPersistedTarget(input),
+            delivery: null,
+            deliveryConfirmationPending: false,
+            deliveryIdempotencyKey: normalizeNullableString(input.deliveryIdempotencyKey),
+            deliveryTransportIdempotent: false,
+            lastError: null,
+        });
+        await writeJsonFileAtomic(resolveAssistantOutboxIntentPath(paths.outboxDirectory, intent.intentId), intent);
+        await appendAssistantTurnReceiptEvent({
+            vault: input.vault,
+            turnId: input.turnId,
+            kind: 'delivery.queued',
+            detail: 'outbound delivery queued',
+            metadata: {
+                intentId: intent.intentId,
+                channel: intent.channel ?? 'unknown',
+            },
+            at: createdAt,
+        });
+        await updateAssistantTurnReceipt({
+            vault: input.vault,
+            turnId: input.turnId,
+            mutate(receipt) {
+                return {
+                    ...receipt,
+                    updatedAt: createdAt,
+                    deliveryDisposition: 'queued',
+                    deliveryIntentId: intent.intentId,
+                };
+            },
+        });
+        await recordAssistantDiagnosticEvent({
+            vault: input.vault,
+            component: 'outbox',
+            kind: 'delivery.queued',
+            message: `Queued outbound delivery for ${intent.channel ?? 'unknown'} channel.`,
+            sessionId: intent.sessionId,
+            turnId: intent.turnId,
+            intentId: intent.intentId,
+            counterDeltas: {
+                deliveriesQueued: 1,
+            },
+        });
+        return intent;
+    });
+}
+export async function readAssistantOutboxIntent(vault, intentId) {
+    const paths = resolveAssistantStatePaths(vault);
+    await ensureAssistantState(paths);
+    try {
+        const parsed = JSON.parse(await readFile(resolveAssistantOutboxIntentPath(paths.outboxDirectory, intentId), 'utf8'));
+        return assistantOutboxIntentSchema.parse(parsed);
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function saveAssistantOutboxIntent(vault, intent) {
+    return withAssistantRuntimeWriteLock(vault, async (paths) => {
+        await ensureAssistantState(paths);
+        const parsed = assistantOutboxIntentSchema.parse(intent);
+        await writeJsonFileAtomic(resolveAssistantOutboxIntentPath(paths.outboxDirectory, parsed.intentId), parsed);
+        return parsed;
+    });
+}
+export async function listAssistantOutboxIntents(vault) {
+    return listAssistantOutboxIntentsLocal(vault);
+}
+export async function listAssistantOutboxIntentsLocal(vault) {
+    const paths = resolveAssistantStatePaths(vault);
+    await ensureAssistantState(paths);
+    const entries = await readdir(paths.outboxDirectory, {
+        withFileTypes: true,
+    });
+    const intents = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.json')) {
+            continue;
+        }
+        const intent = await readAssistantOutboxIntentInventoryEntry(vault, path.join(paths.outboxDirectory, entry.name));
+        if (intent) {
+            intents.push(intent);
+        }
+    }
+    return intents.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+}
+export async function dispatchAssistantOutboxIntent(input) {
+    const now = input.now ?? new Date();
+    const prepared = await withAssistantRuntimeWriteLock(input.vault, async (paths) => {
+        await ensureAssistantState(paths);
+        const intentPath = resolveAssistantOutboxIntentPath(paths.outboxDirectory, input.intentId);
+        const intent = await readAssistantOutboxIntentAtPath(intentPath);
+        if (!intent) {
+            throw new Error(`Assistant outbox intent ${input.intentId} was not found.`);
+        }
+        if (!shouldBeginAssistantOutboxDispatch(intent, now, input.force === true)) {
+            return {
+                action: 'skip',
+                intent,
+            };
+        }
+        if (intent.deliveryConfirmationPending && !intent.deliveryTransportIdempotent) {
+            return {
+                action: 'reconcile',
+                intent,
+                intentPath,
+            };
+        }
+        const startedAt = now.toISOString();
+        const sending = assistantOutboxIntentSchema.parse({
+            ...intent,
+            deliveryIdempotencyKey: intent.deliveryIdempotencyKey ?? buildAssistantDeliveryIdempotencyKey(intent),
+            updatedAt: startedAt,
+            lastAttemptAt: startedAt,
+            attemptCount: intent.attemptCount + 1,
+            status: 'sending',
+        });
+        await writeJsonFileAtomic(intentPath, sending);
+        await appendAssistantTurnReceiptEvent({
+            vault: input.vault,
+            turnId: sending.turnId,
+            kind: 'delivery.attempt.started',
+            detail: `attempt ${sending.attemptCount}`,
+            metadata: {
+                intentId: sending.intentId,
+                attempt: String(sending.attemptCount),
+            },
+            at: startedAt,
+        });
+        return {
+            action: 'dispatch',
+            intent,
+            intentPath,
+            sending,
+        };
+    });
+    if (prepared.action === 'skip') {
+        return {
+            intent: prepared.intent,
+            deliveryError: prepared.intent.lastError,
+            session: null,
+        };
+    }
+    const dispatchIntent = prepared.action === 'dispatch' ? prepared.sending : prepared.intent;
+    const dispatchIntentPath = prepared.intentPath;
+    let deliveryMayHaveSucceeded = false;
+    let deliveryTransportIdempotent = dispatchIntent.deliveryTransportIdempotent;
+    let preparedDispatchReserved = false;
+    try {
+        const reconciledDelivery = (await input.dispatchHooks?.resolveDeliveredIntent?.({
+            intent: dispatchIntent,
+            vault: input.vault,
+        })) ?? null;
+        if (reconciledDelivery) {
+            const sentIntent = await markAssistantOutboxIntentSent({
+                delivery: reconciledDelivery,
+                intent: prepared.intent,
+                intentPath: dispatchIntentPath,
+                preserveCurrentDispatchMetadata: false,
+                vault: input.vault,
+            });
+            return {
+                intent: sentIntent,
+                deliveryError: null,
+                session: null,
+            };
+        }
+        if (dispatchIntent.deliveryConfirmationPending &&
+            !dispatchIntent.deliveryTransportIdempotent) {
+            const retryIntent = await rescheduleAssistantOutboxConfirmationRetry({
+                error: createAssistantDeliveryConfirmationPendingError(),
+                intentPath: dispatchIntentPath,
+                now,
+                sending: dispatchIntent,
+                vault: input.vault,
+            });
+            return {
+                intent: retryIntent,
+                deliveryError: retryIntent.lastError,
+                session: null,
+            };
+        }
+        maybeThrowInjectedAssistantFault({
+            component: 'delivery',
+            fault: 'delivery',
+            message: 'Injected assistant delivery failure.',
+        });
+        await input.dispatchHooks?.prepareDispatchIntent?.({
+            intent: dispatchIntent,
+            vault: input.vault,
+        });
+        preparedDispatchReserved = input.dispatchHooks?.prepareDispatchIntent !== undefined;
+        const delivered = await deliverAssistantMessageOverBinding({
+            vault: input.vault,
+            sessionId: dispatchIntent.sessionId,
+            message: dispatchIntent.message,
+            channel: dispatchIntent.channel,
+            idempotencyKey: dispatchIntent.deliveryIdempotencyKey,
+            identityId: dispatchIntent.identityId,
+            actorId: dispatchIntent.actorId,
+            threadId: dispatchIntent.threadId,
+            threadIsDirect: dispatchIntent.threadIsDirect,
+            replyToMessageId: dispatchIntent.replyToMessageId,
+            target: dispatchIntent.explicitTarget ?? null,
+            session: {
+                binding: {
+                    conversationKey: null,
+                    channel: dispatchIntent.channel,
+                    identityId: dispatchIntent.identityId,
+                    actorId: dispatchIntent.actorId,
+                    threadId: dispatchIntent.threadId,
+                    threadIsDirect: dispatchIntent.threadIsDirect,
+                    delivery: dispatchIntent.bindingDelivery,
+                },
+            },
+        }, input.dependencies);
+        const delivery = assistantChannelDeliverySchema.parse({
+            ...delivered.delivery,
+            idempotencyKey: delivered.delivery.idempotencyKey ??
+                dispatchIntent.deliveryIdempotencyKey,
+        });
+        deliveryTransportIdempotent = delivered.deliveryTransportIdempotent === true;
+        deliveryMayHaveSucceeded = true;
+        const deliveredIntent = assistantOutboxIntentSchema.parse({
+            ...dispatchIntent,
+            deliveryTransportIdempotent,
+        });
+        const durableDeliveredIntent = input.dispatchHooks?.persistDeliveredIntent
+            ? await persistAssistantOutboxIntentDeliveryPendingConfirmation({
+                delivery,
+                deliveryTransportIdempotent,
+                intent: deliveredIntent,
+                intentPath: dispatchIntentPath,
+                vault: input.vault,
+            })
+            : deliveredIntent;
+        await input.dispatchHooks?.persistDeliveredIntent?.({
+            delivery,
+            intent: durableDeliveredIntent,
+            vault: input.vault,
+        });
+        preparedDispatchReserved = false;
+        if (delivered.session) {
+            try {
+                await saveAssistantSession(input.vault, delivered.session);
+            }
+            catch (error) {
+                warnAssistantBestEffortFailure({
+                    error,
+                    operation: 'post-delivery session persistence',
+                });
+            }
+        }
+        const sentIntent = await markAssistantOutboxIntentSent({
+            delivery,
+            intent: durableDeliveredIntent,
+            intentPath: dispatchIntentPath,
+            vault: input.vault,
+        });
+        return {
+            intent: sentIntent,
+            deliveryError: null,
+            session: delivered.session ?? null,
+        };
+    }
+    catch (error) {
+        let failure = error;
+        let effectiveDeliveryMayHaveSucceeded = deliveryMayHaveSucceeded || errorImpliesAssistantDeliveryMayHaveSucceeded(error);
+        if (preparedDispatchReserved && !effectiveDeliveryMayHaveSucceeded) {
+            if (input.dispatchHooks?.clearPreparedIntent) {
+                try {
+                    await input.dispatchHooks.clearPreparedIntent({
+                        intent: dispatchIntent,
+                        vault: input.vault,
+                    });
+                    preparedDispatchReserved = false;
+                }
+                catch (clearError) {
+                    failure = clearError;
+                    effectiveDeliveryMayHaveSucceeded = true;
+                }
+            }
+            else {
+                effectiveDeliveryMayHaveSucceeded = true;
+            }
+        }
+        const failedIntent = await updateAssistantOutboxAfterDispatchFailure({
+            deliveryMayHaveSucceeded: effectiveDeliveryMayHaveSucceeded,
+            deliveryTransportIdempotent,
+            error: failure,
+            intentPath: dispatchIntentPath,
+            now,
+            sending: dispatchIntent,
+            vault: input.vault,
+        });
+        return {
+            intent: failedIntent,
+            deliveryError: failedIntent.lastError,
+            session: null,
+        };
+    }
+}
+export async function deliverAssistantOutboxMessage(input) {
+    const intent = await createAssistantOutboxIntent({
+        actorId: input.actorId,
+        bindingDelivery: input.bindingDelivery,
+        channel: input.channel,
+        dedupeToken: input.dedupeToken,
+        deliveryIdempotencyKey: input.deliveryIdempotencyKey,
+        explicitTarget: input.explicitTarget,
+        identityId: input.identityId,
+        message: input.message,
+        replyToMessageId: input.replyToMessageId,
+        sessionId: input.sessionId,
+        threadId: input.threadId,
+        threadIsDirect: input.threadIsDirect,
+        turnId: input.turnId,
+        vault: input.vault,
+    });
+    if (intent.status === 'sent' && intent.delivery) {
+        return {
+            kind: 'sent',
+            intent,
+            delivery: intent.delivery,
+            deliveryError: null,
+            session: null,
+        };
+    }
+    if ((input.dispatchMode ?? 'immediate') === 'queue-only') {
+        return {
+            kind: 'queued',
+            intent,
+            delivery: null,
+            deliveryError: null,
+            session: null,
+        };
+    }
+    const dispatched = await dispatchAssistantOutboxIntent({
+        dependencies: input.dependencies,
+        dispatchHooks: input.dispatchHooks,
+        force: true,
+        intentId: intent.intentId,
+        vault: input.vault,
+    });
+    if (dispatched.intent.status === 'sent' && dispatched.intent.delivery) {
+        return {
+            kind: 'sent',
+            intent: dispatched.intent,
+            delivery: dispatched.intent.delivery,
+            deliveryError: null,
+            session: dispatched.session ?? null,
+        };
+    }
+    if (dispatched.intent.status === 'pending' ||
+        dispatched.intent.status === 'retryable' ||
+        dispatched.intent.status === 'sending') {
+        return {
+            kind: 'queued',
+            intent: dispatched.intent,
+            delivery: null,
+            deliveryError: dispatched.deliveryError,
+            session: dispatched.session ?? null,
+        };
+    }
+    return {
+        kind: 'failed',
+        intent: dispatched.intent,
+        delivery: null,
+        deliveryError: dispatched.deliveryError ??
+            normalizeAssistantDeliveryError(new Error('Assistant outbound delivery failed.')),
+        session: dispatched.session ?? null,
+    };
+}
+export async function drainAssistantOutbox(input) {
+    return drainAssistantOutboxLocal(input);
+}
+export async function drainAssistantOutboxLocal(input) {
+    maybeThrowInjectedAssistantFault({
+        component: 'outbox',
+        fault: 'outbox',
+        message: 'Injected assistant outbox drain failure.',
+    });
+    const now = input.now ?? new Date();
+    const intents = await listAssistantOutboxIntents(input.vault);
+    const due = intents.filter((intent) => shouldDispatchAssistantOutboxIntent(intent, now));
+    const limit = Math.max(0, Math.trunc(input.limit ?? due.length));
+    const selected = due.slice(0, limit);
+    let sent = 0;
+    let failed = 0;
+    let queued = 0;
+    if (selected.length > 0) {
+        await recordAssistantDiagnosticEvent({
+            vault: input.vault,
+            component: 'outbox',
+            kind: 'outbox.drain',
+            message: `Draining ${selected.length} assistant outbox intent(s).`,
+            counterDeltas: {
+                outboxDrains: 1,
+            },
+        });
+    }
+    for (const intent of selected) {
+        const dispatched = await dispatchAssistantOutboxIntent({
+            dependencies: input.dependencies,
+            dispatchHooks: input.dispatchHooks,
+            vault: input.vault,
+            intentId: intent.intentId,
+            now,
+        });
+        switch (dispatched.intent.status) {
+            case 'sent':
+                sent += 1;
+                break;
+            case 'retryable':
+            case 'pending':
+            case 'sending':
+                queued += 1;
+                break;
+            default:
+                failed += 1;
+                break;
+        }
+    }
+    return {
+        attempted: selected.length,
+        sent,
+        failed,
+        queued,
+    };
+}
+async function persistAssistantOutboxIntentDeliveryPendingConfirmation(input) {
+    return withAssistantRuntimeWriteLock(input.vault, async (paths) => {
+        await ensureAssistantState(paths);
+        const current = await readAssistantOutboxIntentAtPath(input.intentPath);
+        const baseIntent = current ?? input.intent;
+        const pendingIntent = assistantOutboxIntentSchema.parse({
+            ...baseIntent,
+            deliveryConfirmationPending: true,
+            deliveryTransportIdempotent: input.deliveryTransportIdempotent,
+            deliveryIdempotencyKey: input.delivery.idempotencyKey ?? baseIntent.deliveryIdempotencyKey,
+            updatedAt: input.delivery.sentAt,
+            nextAttemptAt: null,
+            status: 'sending',
+            delivery: input.delivery,
+            lastError: createAssistantDeliveryConfirmationPendingError(),
+        });
+        await writeJsonFileAtomic(input.intentPath, pendingIntent);
+        return pendingIntent;
+    });
+}
+function errorImpliesAssistantDeliveryMayHaveSucceeded(error) {
+    if (typeof error === 'object' &&
+        error !== null &&
+        'deliveryMayHaveSucceeded' in error &&
+        typeof error.deliveryMayHaveSucceeded === 'boolean') {
+        return error.deliveryMayHaveSucceeded;
+    }
+    return normalizeAssistantDeliveryError(error).code === 'ASSISTANT_DELIVERY_CONFIRMATION_PENDING';
+}
+function sameAssistantChannelDelivery(left, right) {
+    return (left.channel === right.channel &&
+        left.idempotencyKey === right.idempotencyKey &&
+        left.target === right.target &&
+        left.targetKind === right.targetKind &&
+        left.sentAt === right.sentAt &&
+        left.messageLength === right.messageLength &&
+        left.providerMessageId === right.providerMessageId &&
+        left.providerThreadId === right.providerThreadId);
+}
+async function markAssistantOutboxIntentSent(input) {
+    const completedAt = input.delivery.sentAt;
+    return withAssistantRuntimeWriteLock(input.vault, async (paths) => {
+        await ensureAssistantState(paths);
+        const current = await readAssistantOutboxIntentAtPath(input.intentPath);
+        if (current?.status === 'sent' &&
+            current.delivery &&
+            sameAssistantChannelDelivery(current.delivery, input.delivery)) {
+            return current;
+        }
+        const baseIntent = input.preserveCurrentDispatchMetadata === false
+            ? input.intent
+            : current ?? input.intent;
+        const sentIntent = assistantOutboxIntentSchema.parse({
+            ...baseIntent,
+            deliveryConfirmationPending: false,
+            deliveryIdempotencyKey: input.delivery.idempotencyKey ?? baseIntent.deliveryIdempotencyKey,
+            updatedAt: completedAt,
+            nextAttemptAt: null,
+            sentAt: completedAt,
+            status: 'sent',
+            delivery: input.delivery,
+            lastError: null,
+        });
+        await writeJsonFileAtomic(input.intentPath, sentIntent);
+        await appendAssistantTurnReceiptEvent({
+            vault: input.vault,
+            turnId: sentIntent.turnId,
+            kind: 'delivery.sent',
+            detail: input.delivery.target,
+            metadata: {
+                intentId: sentIntent.intentId,
+                channel: input.delivery.channel,
+                target: input.delivery.target,
+            },
+            at: completedAt,
+        });
+        await updateAssistantTurnReceipt({
+            vault: input.vault,
+            turnId: sentIntent.turnId,
+            mutate(receipt) {
+                return {
+                    ...receipt,
+                    updatedAt: completedAt,
+                    completedAt,
+                    status: receipt.status === 'failed' ? 'failed' : 'completed',
+                    deliveryDisposition: 'sent',
+                    lastError: null,
+                };
+            },
+        });
+        await recordAssistantDiagnosticEvent({
+            vault: input.vault,
+            component: 'delivery',
+            kind: 'delivery.sent',
+            message: `Delivered outbound assistant reply over ${input.delivery.channel}.`,
+            sessionId: sentIntent.sessionId,
+            turnId: sentIntent.turnId,
+            intentId: sentIntent.intentId,
+            counterDeltas: {
+                deliveriesSent: 1,
+            },
+            at: completedAt,
+        });
+        return sentIntent;
+    });
+}
+export async function buildAssistantOutboxSummary(vault) {
+    const intents = await listAssistantOutboxIntents(vault);
+    let oldestPendingAt = null;
+    let nextAttemptAt = null;
+    for (const intent of intents) {
+        if ((intent.status === 'pending' || intent.status === 'retryable' || intent.status === 'sending') &&
+            (!oldestPendingAt || intent.createdAt < oldestPendingAt)) {
+            oldestPendingAt = intent.createdAt;
+        }
+        if ((intent.status === 'pending' || intent.status === 'retryable') &&
+            intent.nextAttemptAt &&
+            (!nextAttemptAt || intent.nextAttemptAt < nextAttemptAt)) {
+            nextAttemptAt = intent.nextAttemptAt;
+        }
+    }
+    return {
+        total: intents.length,
+        pending: intents.filter((intent) => intent.status === 'pending').length,
+        sending: intents.filter((intent) => intent.status === 'sending').length,
+        retryable: intents.filter((intent) => intent.status === 'retryable').length,
+        sent: intents.filter((intent) => intent.status === 'sent').length,
+        failed: intents.filter((intent) => intent.status === 'failed').length,
+        abandoned: intents.filter((intent) => intent.status === 'abandoned').length,
+        oldestPendingAt,
+        nextAttemptAt,
+    };
+}
+function normalizeRequiredMessage(value) {
+    const normalized = normalizeNullableString(value);
+    if (!normalized) {
+        throw new Error('Assistant outbox messages must be non-empty strings.');
+    }
+    return normalized;
+}
+async function findAssistantOutboxIntentByDedupeKey(vault, dedupeKey) {
+    const intents = await listAssistantOutboxIntents(vault);
+    return (intents.find((intent) => {
+        if (intent.dedupeKey !== dedupeKey) {
+            return false;
+        }
+        return intent.status !== 'failed' && intent.status !== 'abandoned';
+    }) ?? null);
+}
+async function readAssistantOutboxIntentAtPath(intentPath) {
+    try {
+        const parsed = JSON.parse(await readFile(intentPath, 'utf8'));
+        return assistantOutboxIntentSchema.parse(parsed);
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+async function readAssistantOutboxIntentInventoryEntry(vault, intentPath) {
+    try {
+        return await readAssistantOutboxIntentAtPath(intentPath);
+    }
+    catch (error) {
+        await quarantineAssistantOutboxIntentFile({
+            error,
+            intentPath,
+            vault,
+        });
+        return null;
+    }
+}
+async function quarantineAssistantOutboxIntentFile(input) {
+    const paths = resolveAssistantStatePaths(input.vault);
+    const quarantineDirectory = resolveAssistantOutboxQuarantineDirectory(paths.outboxDirectory);
+    const basename = path.basename(input.intentPath, '.json');
+    const quarantinePath = path.join(quarantineDirectory, `${basename}.${Date.now()}.invalid.json`);
+    try {
+        await ensureAssistantStateDirectory(quarantineDirectory);
+        await rename(input.intentPath, quarantinePath);
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return;
+        }
+        throw error;
+    }
+    try {
+        await recordAssistantDiagnosticEvent({
+            vault: input.vault,
+            component: 'outbox',
+            kind: 'outbox.intent.quarantined',
+            level: 'warn',
+            message: normalizeAssistantDeliveryError(input.error).message,
+        });
+    }
+    catch { }
+}
+async function updateAssistantOutboxAfterDispatchFailure(input) {
+    const deliveryError = input.deliveryMayHaveSucceeded
+        ? createAssistantDeliveryConfirmationPendingError(input.error)
+        : normalizeAssistantDeliveryError(input.error);
+    const retryable = input.deliveryMayHaveSucceeded || isAssistantOutboxRetryableError(input.error);
+    return withAssistantRuntimeWriteLock(input.vault, async (paths) => {
+        await ensureAssistantState(paths);
+        const current = await readAssistantOutboxIntentAtPath(input.intentPath);
+        const attemptCount = current?.attemptCount ?? input.sending.attemptCount;
+        const updatedAt = new Date().toISOString();
+        const nextAttemptAt = retryable
+            ? new Date(input.now.getTime() + resolveAssistantOutboxRetryDelayMs(attemptCount)).toISOString()
+            : null;
+        const failedIntent = assistantOutboxIntentSchema.parse({
+            ...(current ?? input.sending),
+            deliveryConfirmationPending: input.deliveryMayHaveSucceeded,
+            deliveryTransportIdempotent: input.deliveryMayHaveSucceeded
+                ? input.deliveryTransportIdempotent
+                : (current?.deliveryTransportIdempotent ?? input.sending.deliveryTransportIdempotent),
+            updatedAt,
+            nextAttemptAt,
+            status: retryable ? 'retryable' : 'failed',
+            lastError: deliveryError,
+        });
+        await writeJsonFileAtomic(input.intentPath, failedIntent);
+        await appendAssistantTurnReceiptEvent({
+            vault: input.vault,
+            turnId: failedIntent.turnId,
+            kind: retryable ? 'delivery.retry-scheduled' : 'delivery.failed',
+            detail: deliveryError.message,
+            metadata: {
+                intentId: failedIntent.intentId,
+                retryable: retryable ? 'true' : 'false',
+            },
+            at: failedIntent.updatedAt,
+        });
+        await updateAssistantTurnReceipt({
+            vault: input.vault,
+            turnId: failedIntent.turnId,
+            mutate(receipt) {
+                return {
+                    ...receipt,
+                    updatedAt: failedIntent.updatedAt,
+                    status: retryable ? 'deferred' : 'failed',
+                    deliveryDisposition: retryable ? 'retryable' : 'failed',
+                    lastError: deliveryError,
+                };
+            },
+        });
+        await recordAssistantDiagnosticEvent({
+            vault: input.vault,
+            component: retryable ? 'outbox' : 'delivery',
+            kind: retryable ? 'delivery.retry-scheduled' : 'delivery.failed',
+            message: deliveryError.message,
+            level: retryable ? 'warn' : 'error',
+            code: deliveryError.code,
+            sessionId: failedIntent.sessionId,
+            turnId: failedIntent.turnId,
+            intentId: failedIntent.intentId,
+            counterDeltas: retryable
+                ? {
+                    deliveriesRetryable: 1,
+                    outboxRetries: 1,
+                }
+                : {
+                    deliveriesFailed: 1,
+                },
+        });
+        return failedIntent;
+    });
+}
+async function rescheduleAssistantOutboxConfirmationRetry(input) {
+    return withAssistantRuntimeWriteLock(input.vault, async (paths) => {
+        await ensureAssistantState(paths);
+        const current = await readAssistantOutboxIntentAtPath(input.intentPath);
+        const baseIntent = current ?? input.sending;
+        const updatedAt = new Date().toISOString();
+        const retryIntent = assistantOutboxIntentSchema.parse({
+            ...baseIntent,
+            deliveryConfirmationPending: true,
+            updatedAt,
+            nextAttemptAt: new Date(input.now.getTime() + resolveAssistantOutboxRetryDelayMs(baseIntent.attemptCount)).toISOString(),
+            status: 'retryable',
+            lastError: input.error,
+        });
+        await writeJsonFileAtomic(input.intentPath, retryIntent);
+        return retryIntent;
+    });
+}
+function buildAssistantDeliveryIdempotencyKey(intent) {
+    return `assistant-outbox:${intent.intentId}`;
+}
+//# sourceMappingURL=outbox.js.map