@scotthuang/agent-knock-knock 0.12.13 → 0.12.14

package/dist/src/deferred-foreground-transfer.js

@@ -10,6 +10,39 @@ export const DEFERRED_FOREGROUND_TRANSFER_SCHEMA = "agent-knock-knock/deferred-f
 export const DEFERRED_FOREGROUND_TRANSFER_VERSION = 2;
 export const DEFERRED_FOREGROUND_TRANSFER_LEGACY_VERSION = 1;
 const TRANSFER_STATE_FILE = "state.json";
+export function deferredForegroundActiveMessageId(transfer) {
+    return transfer.submission_retry_message_id ?? transfer.message_id;
+}
+export function deferredForegroundActivePreparedAt(transfer) {
+    return transfer.submission_retry_prepared_at ?? transfer.prepared_at;
+}
+export function isDeferredForegroundSubmissionRetryPending(transfer) {
+    const common = transfer.status === "uncertain" &&
+        transfer.input_stage === "enter_dispatched" &&
+        Boolean(transfer.submission_retry_attempt_id) &&
+        Boolean(transfer.submission_retry_mode) &&
+        Boolean(transfer.submission_retry_message_id) &&
+        Boolean(transfer.submission_retry_prepared_at) &&
+        Boolean(transfer.submission_retry_enter_reserved_at) &&
+        Boolean(transfer.submission_retry_enter_dispatched_at) &&
+        deferredForegroundActiveMessageId(transfer) ===
+            transfer.submission_retry_message_id;
+    return common && (transfer.submission_retry_mode === "exact_draft_enter"
+        ? transfer.submission_retry_message_id === transfer.message_id &&
+            transfer.submission_retry_text_reserved_at === undefined &&
+            transfer.submission_retry_text_injected_at === undefined &&
+            Boolean(transfer.text_injected_at)
+        : Boolean(transfer.submission_retry_text_reserved_at) &&
+            Boolean(transfer.submission_retry_text_injected_at));
+}
+export function deferredForegroundActiveTextInjectedAt(transfer) {
+    return transfer.submission_retry_text_injected_at ??
+        transfer.text_injected_at;
+}
+export function deferredForegroundActiveEnterDispatchedAt(transfer) {
+    return transfer.submission_retry_enter_dispatched_at ??
+        transfer.enter_dispatched_at;
+}
 export class DeferredForegroundTransferConflictError extends Error {
     code = "AKK_DEFERRED_FOREGROUND_TRANSFER_CONFLICT";
     transferId;
@@ -54,6 +87,12 @@ export function assertDeferredForegroundTransfer(value, expectedTransferId, opti
     assertDeferredForegroundTransferResolution(transfer);
     assertDeferredForegroundTransferAbort(transfer, provedTerminalInputNotStarted);
     assertDeferredForegroundTransferFailure(transfer);
+    assertDeferredForegroundUserAbandonment(transfer);
+}
+function deferredForegroundEvidenceStatus(value) {
+    return value.status === "user_abandoned"
+        ? value.origin_status ?? value.status
+        : value.status;
 }
 function assertDeferredForegroundTransferHeader(value, expectedTransferId, options) {
     assertOnlyKeys(value, [
@@ -97,6 +136,14 @@ function assertDeferredForegroundTransferHeader(value, expectedTransferId, optio
         "enter_dispatched_at",
         "agent_accepted_at",
         "message_id",
+        "submission_retry_attempt_id",
+        "submission_retry_mode",
+        "submission_retry_message_id",
+        "submission_retry_prepared_at",
+        "submission_retry_text_reserved_at",
+        "submission_retry_text_injected_at",
+        "submission_retry_enter_reserved_at",
+        "submission_retry_enter_dispatched_at",
         "turn_id",
         "state_path",
         "target_native_thread_id",
@@ -132,7 +179,9 @@ function assertDeferredForegroundTransferHeader(value, expectedTransferId, optio
         "uncertain_at",
         "recovered_at",
         "error",
-        "do_not_retry"
+        "do_not_retry",
+        "origin_status",
+        "user_abandoned_at"
     ], "deferred foreground transfer");
     if (value.schema !== DEFERRED_FOREGROUND_TRANSFER_SCHEMA ||
         ![
@@ -347,6 +396,21 @@ function assertDeferredForegroundTransferTarget(value) {
         assertOptionalTimestamp(value[field], `deferred transfer ${field}`);
     }
     assertOptionalNonEmptyString(value.message_id, "deferred transfer message_id");
+    assertOptionalNonEmptyString(value.submission_retry_attempt_id, "deferred transfer submission retry attempt id");
+    if (value.submission_retry_mode !== undefined &&
+        !["exact_draft_enter", "replacement_send"].includes(value.submission_retry_mode)) {
+        throw new Error("deferred transfer submission retry mode is invalid");
+    }
+    assertOptionalNonEmptyString(value.submission_retry_message_id, "deferred transfer submission retry message id");
+    for (const field of [
+        "submission_retry_prepared_at",
+        "submission_retry_text_reserved_at",
+        "submission_retry_text_injected_at",
+        "submission_retry_enter_reserved_at",
+        "submission_retry_enter_dispatched_at"
+    ]) {
+        assertOptionalTimestamp(value[field], `deferred transfer ${field}`);
+    }
     assertOptionalNonEmptyString(value.turn_id, "deferred transfer turn_id");
     if (value.state_path !== undefined) {
         assertAbsolutePath(value.state_path, "deferred transfer state_path");
@@ -357,13 +421,14 @@ function assertDeferredForegroundTransferTarget(value) {
     }
 }
 function assertDeferredForegroundTransferPreparation(value) {
+    const evidenceStatus = deferredForegroundEvidenceStatus(value);
     const requiresTargetPrepared = [
         "target_prepared",
         "dispatch_started",
         "committed",
         "resolved",
         "uncertain"
-    ].includes(String(value.status));
+    ].includes(String(evidenceStatus));
     const targetPreparedFields = [
         value.target_prepared_at,
         value.target_prepared_revision,
@@ -379,7 +444,7 @@ function assertDeferredForegroundTransferPreparation(value) {
     const hasAllTargetPreparedFields = targetPreparedFields.every((field) => field !== undefined);
     if (hasAnyTargetPreparedField !== hasAllTargetPreparedFields ||
         (requiresTargetPrepared && !hasAllTargetPreparedFields)) {
-        throw new Error(`${String(value.status)} deferred transfer requires its target/Turn identity`);
+        throw new Error(`${String(evidenceStatus)} deferred transfer requires its target/Turn identity`);
     }
     if (hasAllTargetPreparedFields) {
         if (!value.source_reserved_at ||
@@ -397,45 +462,89 @@ function assertDeferredForegroundTransferPreparation(value) {
         "resolved",
         "uncertain"
     ]
-        .includes(String(value.status)) &&
+        .includes(String(evidenceStatus)) &&
         !value.source_reserved_at) {
-        throw new Error(`${String(value.status)} deferred transfer requires source_reserved_at`);
+        throw new Error(`${String(evidenceStatus)} deferred transfer requires source_reserved_at`);
     }
-    if (value.status === "prepared" &&
+    if (evidenceStatus === "prepared" &&
         (value.source_reserved_at !== undefined || hasAnyTargetPreparedField)) {
         throw new Error("prepared deferred transfer cannot carry reservation evidence");
     }
-    if (value.status === "source_reserved" && hasAnyTargetPreparedField) {
+    if (evidenceStatus === "source_reserved" && hasAnyTargetPreparedField) {
         throw new Error("source_reserved deferred transfer cannot carry target evidence");
     }
 }
 function assertDeferredForegroundTransferDispatch(value) {
-    if (["dispatch_started", "committed", "resolved", "uncertain"].includes(String(value.status)) &&
+    const evidenceStatus = deferredForegroundEvidenceStatus(value);
+    if (["dispatch_started", "committed", "resolved", "uncertain"].includes(String(evidenceStatus)) &&
         (!value.dispatch_started_at || value.input_stage === "none")) {
-        throw new Error(`${String(value.status)} deferred transfer requires dispatch-start evidence`);
+        throw new Error(`${String(evidenceStatus)} deferred transfer requires dispatch-start evidence`);
     }
     assertInputStageEvidence(value);
     if ([
         "prepared",
         "source_reserved",
         "target_prepared"
-    ].includes(String(value.status)) &&
+    ].includes(String(evidenceStatus)) &&
         value.input_stage !== "none") {
-        throw new Error(`${String(value.status)} deferred transfer cannot carry input evidence`);
+        throw new Error(`${String(evidenceStatus)} deferred transfer cannot carry input evidence`);
     }
-    const provedTerminalInputNotStarted = ["aborted", "abort_resolved"].includes(String(value.status)) &&
+    const provedTerminalInputNotStarted = ["aborted", "abort_resolved"].includes(String(evidenceStatus)) &&
         value.input_stage === "dispatch_started" &&
         value.terminal_input_not_started_at !== undefined;
-    if (["aborted", "abort_resolved"].includes(String(value.status)) &&
+    if (["aborted", "abort_resolved"].includes(String(evidenceStatus)) &&
         value.input_stage !== "none" &&
         !provedTerminalInputNotStarted) {
-        throw new Error(`${String(value.status)} deferred transfer requires exact no-input proof`);
+        throw new Error(`${String(evidenceStatus)} deferred transfer requires exact no-input proof`);
     }
+    assertDeferredForegroundSubmissionRetryEvidence(value);
     assertTimestampOrder(value);
     return provedTerminalInputNotStarted;
 }
+function assertDeferredForegroundSubmissionRetryEvidence(value) {
+    const retryFields = [
+        value.submission_retry_attempt_id,
+        value.submission_retry_mode,
+        value.submission_retry_message_id,
+        value.submission_retry_prepared_at
+    ];
+    const hasAny = retryFields.some((field) => field !== undefined) || [
+        value.submission_retry_text_reserved_at,
+        value.submission_retry_text_injected_at,
+        value.submission_retry_enter_reserved_at,
+        value.submission_retry_enter_dispatched_at
+    ].some((field) => field !== undefined);
+    if (!hasAny)
+        return;
+    const hasCommon = retryFields.every((field) => field !== undefined);
+    const replacement = value.submission_retry_mode === "replacement_send";
+    const exactDraft = value.submission_retry_mode === "exact_draft_enter";
+    const replacementPrefixIsContinuous = value.submission_retry_text_injected_at === undefined ||
+        value.submission_retry_text_reserved_at !== undefined;
+    const enterPrefixIsContinuous = value.submission_retry_enter_reserved_at === undefined ||
+        exactDraft || value.submission_retry_text_injected_at !== undefined;
+    const dispatchPrefixIsContinuous = value.submission_retry_enter_dispatched_at === undefined ||
+        value.submission_retry_enter_reserved_at !== undefined;
+    if (!hasCommon ||
+        !value.uncertain_at ||
+        (!replacement && !exactDraft) ||
+        value.submission_retry_message_id !== value.message_id ||
+        value.submission_retry_prepared_at !== value.prepared_at ||
+        (exactDraft && (value.submission_retry_text_reserved_at !== undefined ||
+            value.submission_retry_text_injected_at !== undefined)) ||
+        !replacementPrefixIsContinuous ||
+        !enterPrefixIsContinuous ||
+        !dispatchPrefixIsContinuous ||
+        (value.input_stage === "enter_dispatched" &&
+            value.submission_retry_enter_dispatched_at === undefined) ||
+        (value.submission_retry_enter_dispatched_at !== undefined &&
+            !["enter_dispatched", "agent_accepted"].includes(value.input_stage))) {
+        throw new Error("deferred foreground submission retry stage evidence is inconsistent");
+    }
+}
 function assertDeferredForegroundTransferCommit(value) {
-    const committed = ["committed", "resolved"].includes(String(value.status));
+    const evidenceStatus = deferredForegroundEvidenceStatus(value);
+    const committed = ["committed", "resolved"].includes(String(evidenceStatus));
     const committedFields = [
         value.target_native_thread_id,
         value.target_accepted_revision,
@@ -510,6 +619,7 @@ function assertDeferredForegroundTransferCommit(value) {
     }
 }
 function assertDeferredForegroundTransferResolution(value) {
+    const evidenceStatus = deferredForegroundEvidenceStatus(value);
     const resolvedFields = [
         value.target_after_revision,
         value.target_after_status,
@@ -522,12 +632,12 @@ function assertDeferredForegroundTransferResolution(value) {
     ];
     const hasAnyResolvedField = resolvedFields.some((field) => field !== undefined);
     const hasAllResolvedFields = resolvedFields.every((field) => field !== undefined);
-    if (value.status === "resolved"
+    if (evidenceStatus === "resolved"
         ? !hasAllResolvedFields
         : hasAnyResolvedField) {
         throw new Error("resolved deferred transfer requires exact final Session evidence");
     }
-    if (value.status === "resolved") {
+    if (evidenceStatus === "resolved") {
         if (!isPositiveSafeInteger(value.target_after_revision) ||
             value.target_after_revision !==
                 Number(value.target_accepted_revision) + 1 ||
@@ -558,7 +668,8 @@ function assertDeferredForegroundTransferResolution(value) {
     }
 }
 function assertDeferredForegroundTransferAbort(value, provedTerminalInputNotStarted) {
-    if (["aborted", "abort_resolved"].includes(String(value.status))
+    const evidenceStatus = deferredForegroundEvidenceStatus(value);
+    if (["aborted", "abort_resolved"].includes(String(evidenceStatus))
         ? !value.aborted_at || !(value.input_stage === "none" || provedTerminalInputNotStarted)
         : value.aborted_at !== undefined) {
         throw new Error("only a proven zero-input deferred transfer can carry an aborted receipt");
@@ -569,7 +680,7 @@ function assertDeferredForegroundTransferAbort(value, provedTerminalInputNotStar
             value.enter_dispatched_at !== undefined ||
             value.agent_accepted_at !== undefined
         : value.input_stage === "dispatch_started" &&
-            ["aborted", "abort_resolved"].includes(String(value.status))) {
+            ["aborted", "abort_resolved"].includes(String(evidenceStatus))) {
         throw new Error("terminal-input-not-started proof must fence only a dispatch intent");
     }
     const abortCleanupSourceFields = [
@@ -589,7 +700,7 @@ function assertDeferredForegroundTransferAbort(value, provedTerminalInputNotStar
         ...abortCleanupSourceFields,
         ...abortCleanupTargetFields
     ].some((field) => field !== undefined);
-    if (value.status === "abort_resolved") {
+    if (evidenceStatus === "abort_resolved") {
         if (abortCleanupSourceFields.some((field) => field === undefined)) {
             throw new Error("resolved deferred abort requires exact source cleanup evidence");
         }
@@ -649,10 +760,11 @@ function assertDeferredForegroundTransferAbort(value, provedTerminalInputNotStar
     }
 }
 function assertDeferredForegroundTransferFailure(value) {
-    if (value.status === "uncertain"
+    const evidenceStatus = deferredForegroundEvidenceStatus(value);
+    if (evidenceStatus === "uncertain"
         ? !value.uncertain_at || value.do_not_retry !== true ||
             value.input_stage === "none"
-        : ["committed", "resolved"].includes(String(value.status)) &&
+        : ["committed", "resolved"].includes(String(evidenceStatus)) &&
             value.uncertain_at !== undefined
             ? !value.recovered_at || value.do_not_retry !== true
             : value.uncertain_at !== undefined ||
@@ -666,10 +778,25 @@ function assertDeferredForegroundTransferFailure(value) {
             "abort_resolved",
             "uncertain",
             ...(value.recovered_at ? ["committed", "resolved"] : [])
-        ].includes(String(value.status))) {
+        ].includes(String(evidenceStatus))) {
         throw new Error("deferred transfer error is allowed only on failure/recovery receipts");
     }
 }
+function assertDeferredForegroundUserAbandonment(value) {
+    const origin = value.origin_status;
+    const abandonedAt = value.user_abandoned_at;
+    if (value.status !== "user_abandoned") {
+        if (origin !== undefined || abandonedAt !== undefined) {
+            throw new Error("user abandonment evidence is allowed only on a user_abandoned receipt");
+        }
+        return;
+    }
+    if (!USER_ABANDONMENT_ORIGIN_STATUSES.has(origin) ||
+        abandonedAt === undefined) {
+        throw new Error("user_abandoned deferred transfer requires its origin status and timestamp");
+    }
+    assertTimestamp(abandonedAt, "deferred transfer user_abandoned_at");
+}
 export function saveDeferredForegroundTransfer(storeDir, value, options) {
     assertDeferredForegroundTransfer(value, undefined, {
         allowMissingRevision: true
@@ -773,20 +900,24 @@ function assertTransferAdvance(current, candidate) {
             `immutable ${changed}`);
     }
     const allowed = {
-        prepared: ["source_reserved", "aborted"],
-        source_reserved: ["target_prepared", "aborted"],
-        target_prepared: ["dispatch_started", "uncertain", "aborted"],
+        prepared: ["source_reserved", "aborted", "user_abandoned"],
+        source_reserved: ["target_prepared", "aborted", "user_abandoned"],
+        target_prepared: [
+            "dispatch_started", "uncertain", "aborted", "user_abandoned"
+        ],
         dispatch_started: [
             "dispatch_started",
             "committed",
             "uncertain",
-            "aborted"
+            "aborted",
+            "user_abandoned"
         ],
-        committed: ["resolved"],
+        committed: ["resolved", "user_abandoned"],
         resolved: [],
-        aborted: ["abort_resolved"],
+        aborted: ["abort_resolved", "user_abandoned"],
         abort_resolved: [],
-        uncertain: ["committed"]
+        uncertain: ["uncertain", "committed", "user_abandoned"],
+        user_abandoned: []
     };
     if (!allowed[current.status].includes(candidate.status)) {
         throw new Error(`deferred foreground transfer cannot move from ${current.status} to ` +
@@ -811,6 +942,21 @@ function assertTransferAdvance(current, candidate) {
             throw new Error(`deferred foreground transfer ${current.transfer_id} cannot change ${field}`);
         }
     }
+    for (const field of [
+        "submission_retry_attempt_id",
+        "submission_retry_mode",
+        "submission_retry_message_id",
+        "submission_retry_prepared_at",
+        "submission_retry_text_reserved_at",
+        "submission_retry_text_injected_at",
+        "submission_retry_enter_reserved_at",
+        "submission_retry_enter_dispatched_at"
+    ]) {
+        if (current[field] !== undefined &&
+            JSON.stringify(current[field]) !== JSON.stringify(candidate[field])) {
+            throw new Error(`deferred foreground transfer ${current.transfer_id} cannot change ${field}`);
+        }
+    }
     for (const field of [
         "source_reserved_at",
         "target_prepared_at",
@@ -851,13 +997,19 @@ function assertTransferAdvance(current, candidate) {
         "uncertain_at",
         "recovered_at",
         "error",
-        "do_not_retry"
+        "do_not_retry",
+        "origin_status",
+        "user_abandoned_at"
     ]) {
         if (current[field] !== undefined &&
             JSON.stringify(current[field]) !== JSON.stringify(candidate[field])) {
             throw new Error(`deferred foreground transfer ${current.transfer_id} cannot change ${field}`);
         }
     }
+    if (candidate.status === "user_abandoned" &&
+        candidate.origin_status !== current.status) {
+        throw new Error("deferred foreground user abandonment must freeze its origin status");
+    }
     if (candidate.status === "aborted" &&
         current.input_stage !== "none" &&
         !(current.input_stage === "dispatch_started" &&
@@ -865,6 +1017,37 @@ function assertTransferAdvance(current, candidate) {
             candidate.terminal_input_not_started_at !== undefined)) {
         throw new Error("deferred foreground transfer cannot abort after input may start");
     }
+    if (current.submission_retry_attempt_id === undefined &&
+        candidate.submission_retry_attempt_id !== undefined &&
+        (current.status !== "uncertain" ||
+            candidate.status !== "uncertain" ||
+            current.input_stage !== "text_injected" ||
+            !candidate.submission_retry_mode ||
+            !candidate.submission_retry_message_id ||
+            !candidate.submission_retry_prepared_at)) {
+        throw new Error("deferred foreground submission retry requires uncertain/text_injected authority");
+    }
+    if (candidate.submission_retry_attempt_id !== undefined &&
+        (!candidate.submission_retry_message_id ||
+            !candidate.submission_retry_prepared_at ||
+            !candidate.submission_retry_mode ||
+            !candidate.uncertain_at ||
+            candidate.submission_retry_message_id !== candidate.message_id ||
+            candidate.submission_retry_prepared_at !== candidate.prepared_at ||
+            (candidate.submission_retry_mode === "replacement_send"
+                ? (candidate.submission_retry_text_injected_at !== undefined &&
+                    !candidate.submission_retry_text_reserved_at) ||
+                    (candidate.submission_retry_enter_reserved_at !== undefined &&
+                        !candidate.submission_retry_text_injected_at)
+                : candidate.submission_retry_message_id !== candidate.message_id ||
+                    candidate.submission_retry_text_reserved_at !== undefined ||
+                    candidate.submission_retry_text_injected_at !== undefined) ||
+            (candidate.submission_retry_enter_dispatched_at !== undefined &&
+                (!candidate.submission_retry_enter_reserved_at ||
+                    (candidate.input_stage !== "enter_dispatched" &&
+                        candidate.input_stage !== "agent_accepted"))))) {
+        throw new Error("deferred foreground submission retry stage evidence is inconsistent");
+    }
 }
 function bindingIsMonotonicTargetRefinement(before, after) {
     return before.binding_id === after.binding_id &&
@@ -921,6 +1104,15 @@ function assertTimestampOrder(value) {
         value.agent_accepted_at
     ].filter((candidate) => candidate !== undefined);
     assertMonotonicTimestamps(inputTimeline);
+    if (value.submission_retry_attempt_id) {
+        assertMonotonicTimestamps([
+            value.uncertain_at,
+            value.submission_retry_text_reserved_at,
+            value.submission_retry_text_injected_at,
+            value.submission_retry_enter_reserved_at,
+            value.submission_retry_enter_dispatched_at
+        ].filter((candidate) => candidate !== undefined));
+    }
     const latestInputEvidence = inputTimeline[inputTimeline.length - 1];
     if (value.aborted_at) {
         assertTimestampNotBefore(value.aborted_at, latestInputEvidence);
@@ -936,11 +1128,13 @@ function assertTimestampOrder(value) {
         // Recovery may prove acceptance after uncertainty was recorded, so the
         // uncertainty timestamp is ordered after the evidence known at its own
         // stage, not unconditionally after a later agent_accepted_at.
-        const latestPossibleDispatch = value.enter_dispatched_at ??
-            value.text_injected_at ?? value.dispatch_started_at ??
-            value.target_prepared_at ?? value.source_reserved_at ?? value.prepared_at;
+        const latestPossibleDispatch = value.submission_retry_attempt_id
+            ? value.text_injected_at ?? value.dispatch_started_at
+            : value.enter_dispatched_at ?? value.text_injected_at ?? value.dispatch_started_at ??
+                value.target_prepared_at ?? value.source_reserved_at ?? value.prepared_at;
         assertTimestampNotBefore(value.uncertain_at, latestPossibleDispatch);
-        if (value.status === "uncertain" && value.input_stage === "agent_accepted") {
+        if (deferredForegroundEvidenceStatus(value) === "uncertain" &&
+            value.input_stage === "agent_accepted") {
             assertTimestampNotBefore(value.uncertain_at, value.agent_accepted_at);
         }
     }
@@ -956,6 +1150,11 @@ function assertTimestampOrder(value) {
         assertTimestampNotBefore(value.resolved_at, value.committed_at);
         assertTimestampNotBefore(value.resolved_at, value.recovered_at);
     }
+    if (value.user_abandoned_at) {
+        assertTimestampNotBefore(value.user_abandoned_at, value.abort_cleanup_completed_at ?? value.resolved_at ??
+            value.recovered_at ?? value.committed_at ?? value.aborted_at ??
+            value.uncertain_at ?? latestInputEvidence);
+    }
 }
 function assertMonotonicTimestamps(values) {
     for (let index = 1; index < values.length; index += 1) {
@@ -1086,6 +1285,16 @@ const TRANSFER_STATUSES = new Set([
     "resolved",
     "aborted",
     "abort_resolved",
+    "uncertain",
+    "user_abandoned"
+]);
+const USER_ABANDONMENT_ORIGIN_STATUSES = new Set([
+    "prepared",
+    "source_reserved",
+    "target_prepared",
+    "dispatch_started",
+    "committed",
+    "aborted",
     "uncertain"
 ]);
 const INPUT_STAGES = new Set([