@scotthuang/agent-knock-knock 0.12.12 → 0.12.13

package/dist/src/terminal-command-cli-adapter.js

@@ -1630,6 +1630,11 @@ async function runApprove(options) {
     }
     const loaded = loadConversationFromOptions(options);
     const { statePath, logPath } = loaded;
+    assertAutoApprovalCallbackRoute({
+        options,
+        conversation: loaded.conversation,
+        statePath
+    });
     const conversation = await migrateLegacyTerminalAgentIdentity({
         ...loaded,
         options
@@ -1641,7 +1646,10 @@ async function runApprove(options) {
     if (!terminalControl) {
         throw new Error(`conversation ${conversation.conversation_id} is not controlled through a terminal`);
     }
-    if (!["waiting_for_agent", "waiting_for_openclaw"].includes(conversation.status)) {
+    const autoApproved = options.autoApproved === true;
+    const callbackAuthority = autoApprovalCallbackAuthorityFromOptions(options);
+    if (!["waiting_for_agent", "waiting_for_openclaw"].includes(conversation.status) &&
+        !(autoApproved && callbackAuthority)) {
         throw new Error(`cannot approve ${conversation.conversation_id}; conversation is ${conversation.status}`);
     }
     const executor = executorForConversation(conversation);
@@ -1651,7 +1659,6 @@ async function runApprove(options) {
     const suppliedExpectedFingerprint = stringValue(options.expectedApprovalFingerprint);
     const expectedFingerprint = suppliedExpectedFingerprint ??
         stringValue(monitoredApproval?.fingerprint);
-    const autoApproved = options.autoApproved === true;
     const claudeScreenApproval = executor.kind === "claude";
     if (claudeScreenApproval) {
         const monitoredState = isRecord(monitoredApproval?.approval_state)
@@ -1665,6 +1672,7 @@ async function runApprove(options) {
         const currentMessageId = stringValue(nativeTakeover?.terminal_bridge_message_id);
         const approvalResolvedAt = validTimestampMs(nativeTakeover?.terminal_bridge_approval_resolved_at);
         if (autoApproved &&
+            callbackAuthority === undefined &&
             monitoredApproval === undefined &&
             pendingDispatch === undefined &&
             conversation.status === "waiting_for_agent" &&
@@ -1693,63 +1701,68 @@ async function runApprove(options) {
             });
             return;
         }
-        const notifiedAt = validTimestampMs(monitoredApproval?.notified_at);
-        if (conversation.status !== "waiting_for_openclaw" ||
-            monitoredState?.decision_mode !== "keys" ||
-            !stringValue(monitoredApproval?.fingerprint)) {
-            printJson({
-                conversation,
-                approved: false,
-                blocked: true,
-                reason: "Claude screen approval requires a current managed-turn approval notification",
-                terminal_control: terminalControl
-            });
-            return;
-        }
-        if (notifiedAt === undefined ||
-            cliNowMs() - notifiedAt > CLAUDE_SCREEN_APPROVAL_TTL_MS) {
-            printJson({
-                conversation,
-                approved: false,
-                blocked: true,
-                reason: "Claude screen approval expired; inspect and resolve the terminal manually",
-                terminal_control: terminalControl
-            });
-            return;
-        }
-        if (!suppliedExpectedFingerprint ||
-            expectedFingerprint !== monitoredApproval?.fingerprint) {
-            printJson({
-                conversation,
-                approved: false,
-                blocked: true,
-                reason: "Claude screen approval requires the latest notified fingerprint",
-                terminal_control: terminalControl
-            });
-            return;
-        }
-        if (pendingDispatch?.state === "reserved" &&
-            pendingDispatch.terminal_bridge_message_id ===
-                nativeTakeover?.terminal_bridge_message_id) {
-            printJson({
-                conversation,
-                approved: false,
-                blocked: true,
-                reason: "a previous Claude approval dispatch has an uncertain outcome; inspect and resolve the terminal manually",
-                terminal_control: terminalControl
-            });
-            return;
-        }
-        if (expectedFingerprint ===
-            stringValue(nativeTakeover?.terminal_bridge_last_approval_fingerprint)) {
-            printJson({
-                conversation,
-                approved: false,
-                blocked: true,
-                reason: "Claude screen approval fingerprint was already consumed",
-                terminal_control: terminalControl
-            });
-            return;
+        // A provenance-bound callback whose approval is already absent must reach
+        // the terminal+state lock.  Only the persisted callback message and the
+        // locked consumed-approval receipt may classify it as an idempotent replay.
+        if (callbackAuthority === undefined || monitoredApproval !== undefined) {
+            const notifiedAt = validTimestampMs(monitoredApproval?.notified_at);
+            if (conversation.status !== "waiting_for_openclaw" ||
+                monitoredState?.decision_mode !== "keys" ||
+                !stringValue(monitoredApproval?.fingerprint)) {
+                printJson({
+                    conversation,
+                    approved: false,
+                    blocked: true,
+                    reason: "Claude screen approval requires a current managed-turn approval notification",
+                    terminal_control: terminalControl
+                });
+                return;
+            }
+            if (notifiedAt === undefined ||
+                cliNowMs() - notifiedAt > CLAUDE_SCREEN_APPROVAL_TTL_MS) {
+                printJson({
+                    conversation,
+                    approved: false,
+                    blocked: true,
+                    reason: "Claude screen approval expired; inspect and resolve the terminal manually",
+                    terminal_control: terminalControl
+                });
+                return;
+            }
+            if (!suppliedExpectedFingerprint ||
+                expectedFingerprint !== monitoredApproval?.fingerprint) {
+                printJson({
+                    conversation,
+                    approved: false,
+                    blocked: true,
+                    reason: "Claude screen approval requires the latest notified fingerprint",
+                    terminal_control: terminalControl
+                });
+                return;
+            }
+            if (pendingDispatch?.state === "reserved" &&
+                pendingDispatch.terminal_bridge_message_id ===
+                    nativeTakeover?.terminal_bridge_message_id) {
+                printJson({
+                    conversation,
+                    approved: false,
+                    blocked: true,
+                    reason: "a previous Claude approval dispatch has an uncertain outcome; inspect and resolve the terminal manually",
+                    terminal_control: terminalControl
+                });
+                return;
+            }
+            if (expectedFingerprint ===
+                stringValue(nativeTakeover?.terminal_bridge_last_approval_fingerprint)) {
+                printJson({
+                    conversation,
+                    approved: false,
+                    blocked: true,
+                    reason: "Claude screen approval fingerprint was already consumed",
+                    terminal_control: terminalControl
+                });
+                return;
+            }
         }
     }
     return runManagedApprovalDispatch({
@@ -1759,6 +1772,28 @@ async function runApprove(options) {
         autoApproved, claudeScreenApproval
     });
 }
+function approvalPolicyCandidateForInspection({ agent, currentTerminalControl, inspection, fingerprint }) {
+    const evidence = inspection.approval.approvable
+        ? inspection.approval.policyEvidence
+        : undefined;
+    return {
+        agent,
+        kind: evidence?.kind ?? inspection.approval.promptKind ?? "unknown",
+        decisionMode: inspection.approval.approvable
+            ? inspection.approval.action.mode ?? "keys"
+            : undefined,
+        command: evidence?.command ?? inspection.approval.command,
+        cwd: evidence?.cwd ?? inspection.approval.cwd ?? currentTerminalControl.currentPath,
+        fingerprint: fingerprint ?? "",
+        terminalTarget: currentTerminalControl.target,
+        ...(evidence?.source === "claude_transcript"
+            ? {
+                evidenceSource: "claude_transcript",
+                evidenceFingerprint: evidence.evidenceFingerprint
+            }
+            : {})
+    };
+}
 async function runManagedApprovalDispatch({ options, conversation, statePath, logPath, nativeTakeover, terminalControl, executor, monitoredApproval, expectedFingerprint, autoApproved, claudeScreenApproval }) {
     const policyRuleId = stringValue(options.policyRuleId);
     const policyFingerprint = stringValue(options.policyFingerprint);
@@ -1766,28 +1801,6 @@ async function runManagedApprovalDispatch({ options, conversation, statePath, lo
         ? parseJsonOption(options.autoApprovalPolicyJson, "--auto-approval-policy-json")
         : undefined;
     let executorPolicyDecision;
-    const policyCandidateForInspection = ({ agent, currentTerminalControl, inspection, fingerprint }) => {
-        const evidence = inspection.approval.approvable
-            ? inspection.approval.policyEvidence
-            : undefined;
-        return {
-            agent,
-            kind: evidence?.kind ?? inspection.approval.promptKind ?? "unknown",
-            decisionMode: inspection.approval.approvable
-                ? inspection.approval.action.mode ?? "keys"
-                : undefined,
-            command: evidence?.command ?? inspection.approval.command,
-            cwd: evidence?.cwd ?? inspection.approval.cwd ?? currentTerminalControl.currentPath,
-            fingerprint: fingerprint ?? "",
-            terminalTarget: currentTerminalControl.target,
-            ...(evidence?.source === "claude_transcript"
-                ? {
-                    evidenceSource: "claude_transcript",
-                    evidenceFingerprint: evidence.evidenceFingerprint
-                }
-                : {})
-        };
-    };
     const releaseTerminalLock = acquireTerminalBridgeSendLock(storeDirFromOptions(options), terminalControl, { timeoutMs: 30000 });
     let terminalLockReleased = false;
     const releaseApprovalTerminalLock = () => {
@@ -1817,21 +1830,43 @@ async function runManagedApprovalDispatch({ options, conversation, statePath, lo
         const currentApproval = isRecord(currentTakeover?.terminal_bridge_approval)
             ? currentTakeover.terminal_bridge_approval
             : undefined;
-        if (currentConversation.status !== conversation.status ||
-            currentTakeover?.terminal_bridge_message_id !== nativeTakeover?.terminal_bridge_message_id ||
-            !currentControl ||
+        const callbackAuthorityState = assertAutoApprovalCallbackAuthority({
+            options,
+            conversation: currentConversation,
+            statePath,
+            takeover: currentTakeover,
+            approval: currentApproval,
+            expectedFingerprint
+        });
+        if (!currentControl ||
             !terminalControlsShareIncarnation(currentControl, terminalControl) ||
-            (claudeScreenApproval &&
-                currentApproval?.fingerprint !== monitoredApproval?.fingerprint)) {
+            (callbackAuthorityState !== "already_approved" &&
+                (currentConversation.status !== conversation.status ||
+                    currentTakeover?.terminal_bridge_message_id !==
+                        nativeTakeover?.terminal_bridge_message_id ||
+                    (claudeScreenApproval &&
+                        currentApproval?.fingerprint !== monitoredApproval?.fingerprint)))) {
             throw new Error("approval state changed while waiting for terminal control; refresh status and retry");
         }
+        lockedConversation = currentConversation;
+        if (callbackAuthorityState === "already_approved") {
+            releaseApprovalStateLock();
+            printJson({
+                conversation: lockedConversation,
+                approved: false,
+                already_approved: true,
+                blocked: false,
+                reason: "automatic approval callback was already handled",
+                terminal_control: currentControl
+            });
+            return;
+        }
         assertManagedTerminalDispatchOwner({
             storeDir: writerStoreDir,
             conversation: currentConversation,
             terminalControl: currentControl,
             action: "approve"
         });
-        lockedConversation = currentConversation;
         const currentRuntimeIdentity = terminalRuntimeIdentityForConversation(currentConversation, currentControl);
         approval = await createTerminalAgentBridge(options).approve(executor.kind, currentControl, {
             expectedFingerprint,
@@ -1847,7 +1882,7 @@ async function runManagedApprovalDispatch({ options, conversation, statePath, lo
                             reason: "automatic approval requires an executor-side policy"
                         };
                     }
-                    const candidate = policyCandidateForInspection({
+                    const candidate = approvalPolicyCandidateForInspection({
                         agent,
                         currentTerminalControl,
                         inspection,
@@ -1887,7 +1922,7 @@ async function runManagedApprovalDispatch({ options, conversation, statePath, lo
                         }
                         const freshPolicyDecision = evaluateApprovalPolicy({
                             policy: autoApprovalPolicy,
-                            candidate: policyCandidateForInspection({
+                            candidate: approvalPolicyCandidateForInspection({
                                 agent: executor.kind,
                                 currentTerminalControl: dispatchControl,
                                 inspection,
@@ -2147,6 +2182,131 @@ async function runManagedApprovalDispatch({ options, conversation, statePath, lo
         }
     }
 }
+function assertAutoApprovalCallbackAuthority(input) {
+    if (input.options.autoApproved !== true) {
+        return "not_callback";
+    }
+    const expected = autoApprovalCallbackAuthorityFromOptions(input.options);
+    if (!expected) {
+        return "not_callback";
+    }
+    assertAutoApprovalCallbackRoute({
+        options: input.options,
+        conversation: input.conversation,
+        statePath: input.statePath
+    });
+    const delivery = isRecord(input.conversation.callback_delivery)
+        ? input.conversation.callback_delivery
+        : undefined;
+    const callbackMessage = isRecord(delivery?.message)
+        ? delivery.message
+        : undefined;
+    const callbackMetadata = isRecord(callbackMessage?.metadata)
+        ? callbackMessage.metadata
+        : undefined;
+    const callbackCandidate = isRecord(callbackMetadata?.approval_candidate)
+        ? callbackMetadata.approval_candidate
+        : undefined;
+    const callbackTerminalStatus = isRecord(callbackMetadata?.terminal_status)
+        ? callbackMetadata.terminal_status
+        : undefined;
+    const callbackApprovalState = isRecord(callbackTerminalStatus?.approval_state)
+        ? callbackTerminalStatus.approval_state
+        : undefined;
+    const persistedApprovalState = isRecord(input.approval?.approval_state)
+        ? input.approval.approval_state
+        : undefined;
+    const callbackFingerprints = [
+        stringValue(callbackMetadata?.approval_fingerprint),
+        stringValue(callbackCandidate?.fingerprint),
+        stringValue(callbackApprovalState?.fingerprint)
+    ];
+    const commonAuthorityMismatch = delivery?.kind !== "approval_notification" ||
+        stringValue(callbackMessage?.id) !== expected.messageId ||
+        stringValue(callbackMessage?.conversation_id) !== expected.conversationId ||
+        stringValue(callbackMessage?.session_id) !== expected.sessionId ||
+        stringValue(callbackMessage?.turn_id) !== expected.turnId ||
+        !input.expectedFingerprint ||
+        !/^[a-f0-9]{64}$/u.test(input.expectedFingerprint) ||
+        callbackFingerprints.some((value) => value !== input.expectedFingerprint) ||
+        input.takeover?.terminal_bridge !== true;
+    if (commonAuthorityMismatch) {
+        throw new Error("automatic approval callback no longer matches the locked Turn state; refresh status and retry");
+    }
+    if (input.approval) {
+        const currentFingerprints = [
+            stringValue(input.approval.fingerprint),
+            stringValue(persistedApprovalState?.fingerprint)
+        ];
+        if (input.conversation.status !== "waiting_for_openclaw" ||
+            currentFingerprints.some((value) => value !== input.expectedFingerprint) ||
+            stringValue(input.approval.callback_message_id) !== expected.messageId) {
+            throw new Error("automatic approval callback no longer matches the locked Turn state; refresh status and retry");
+        }
+        return "current";
+    }
+    if (input.takeover?.terminal_bridge_approval !== undefined ||
+        input.takeover?.terminal_bridge_approval_dispatch !== undefined ||
+        !isPostApprovalCallbackReplayStatus(input.conversation.status) ||
+        stringValue(input.takeover?.terminal_bridge_message_id) !==
+            expected.messageId ||
+        stringValue(input.takeover?.terminal_bridge_last_approval_message_id) !==
+            expected.messageId ||
+        stringValue(input.takeover?.terminal_bridge_last_approval_fingerprint) !==
+            input.expectedFingerprint ||
+        validTimestampMs(input.takeover?.terminal_bridge_approval_resolved_at) === undefined) {
+        throw new Error("automatic approval callback no longer matches the locked Turn receipt; refresh status and retry");
+    }
+    return "already_approved";
+}
+function isPostApprovalCallbackReplayStatus(status) {
+    return [
+        "waiting_for_agent",
+        "running",
+        "idle",
+        "stalled",
+        "callback_pending",
+        "callback_failed",
+        "failed",
+        "closed",
+        "cancelled",
+        "cancelling"
+    ].includes(status);
+}
+function autoApprovalCallbackAuthorityFromOptions(options) {
+    const candidate = {
+        conversationId: stringValue(options.expectedCallbackConversationId),
+        sessionId: stringValue(options.expectedCallbackSessionId),
+        turnId: stringValue(options.expectedCallbackTurnId),
+        messageId: stringValue(options.expectedCallbackMessageId),
+        openclawSession: stringValue(options.expectedCallbackOpenclawSession)
+    };
+    const values = Object.values(candidate);
+    if (values.every((value) => value === undefined)) {
+        return undefined;
+    }
+    if (values.some((value) => value === undefined)) {
+        throw new Error("automatic approval callback identity is incomplete; no approval key was sent");
+    }
+    return candidate;
+}
+function assertAutoApprovalCallbackRoute(input) {
+    if (input.options.autoApproved !== true) {
+        return;
+    }
+    const expected = autoApprovalCallbackAuthorityFromOptions(input.options);
+    if (!expected) {
+        return;
+    }
+    const storedOpenClawSession = stringValue(input.conversation.gateway_session ?? input.conversation.openclaw_session);
+    if (input.conversation.conversation_id !== expected.conversationId ||
+        sessionIdForConversation(input.conversation) !== expected.sessionId ||
+        turnIdForConversation(input.conversation) !== expected.turnId ||
+        !sameCanonicalStatePath(input.conversation.state_path, input.statePath) ||
+        storedOpenClawSession !== expected.openclawSession) {
+        throw new Error("automatic approval callback does not match the selected Turn state; no state was changed");
+    }
+}
 async function runTerminalConversationApprove({ options, terminal }) {
     const { conversationId, agent, terminalControl, pid } = terminal;
     const storeDir = storeDirFromOptions(options);