@scotthuang/agent-knock-knock 0.10.1 → 0.10.3

package/dist/src/openclaw-plugin.js

@@ -1,10 +1,12 @@
 import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import { EXECUTOR_KINDS, executorDefinitionForKind } from "./executors.js";
-import { AKK_CALLBACK_METHOD, akkUsageText, buildAkkCommandCliArgs, formatAkkListCommandResult, formatAkkRespondCommandResult, formatAkkThreadsCommandResult, formatAkkThreadTransitionCommandResult, isAkkThreadTransitionSuccess, parseAkkCommand, resolvePluginStoreDir } from "./openclaw-plugin-helpers.js";
+import { AKK_CALLBACK_METHOD, akkUsageText, buildAkkCommandCliArgs, formatAkkListCommandResult, formatAkkRespondCommandResult, formatAkkThreadsCommandResult, formatAkkThreadTransitionCommandResult, isAkkNativeSubmissionAccepted, isAkkThreadTransitionSuccess, parseAkkCommand, resolvePluginStoreDir } from "./openclaw-plugin-helpers.js";
 import { attemptAutoApproval } from "./approval-policy.js";
 const CALLBACK_METHOD = AKK_CALLBACK_METHOD;
+const MONITOR_SUPERVISOR_INTERVAL_MS = 5_000;
 const defaultBinPath = fileURLToPath(new URL("./cli.js", import.meta.url));
 const relayPathByApi = new WeakMap();
 const sendParameters = {
@@ -310,7 +312,7 @@ const approveParameters = {
         }
     }
 };
-function createPlugin(relayPath) {
+function createPlugin(relayPath, { monitorSupervisorIntervalMs = MONITOR_SUPERVISOR_INTERVAL_MS } = {}) {
     return definePluginEntry({
         id: "agent-knock-knock",
         name: "Agent Knock Knock",
@@ -332,25 +334,7 @@ function createPlugin(relayPath) {
                 }
             }, { scope: "operator.write" });
             try {
-                api.registerService?.({
-                    id: "agent-knock-knock-monitor-reconciliation",
-                    start() {
-                        try {
-                            const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
-                            const args = ["reconcile-monitors"];
-                            pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
-                            const result = runCli(api, args);
-                            api.logger.info?.("agent-knock-knock monitor reconciliation: " +
-                                `checked=${result.checked ?? 0} launched=${result.launched ?? 0} ` +
-                                `already_running=${result.already_running ?? 0} skipped=${result.skipped ?? 0} ` +
-                                `errors=${result.errors ?? 0}`);
-                        }
-                        catch (error) {
-                            const message = error instanceof Error ? error.message : String(error);
-                            api.logger.warn?.(`agent-knock-knock monitor reconciliation skipped after startup error: ${message}`);
-                        }
-                    }
-                });
+                api.registerService?.(createMonitorReconciliationService(api, monitorSupervisorIntervalMs));
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -465,8 +449,13 @@ function createPlugin(relayPath) {
                 name: "agent_knock_knock_send",
                 description: "Start a new turn in an existing AKK session without clearing the coding agent's native context. Target the exact session_id from list or a prior send; never pass a turn id or discovery selector as session_id. selector is compatibility-only for initial live-terminal discovery: use one explicitly named by the user or prefilled by list, and never infer one. Both fields may be omitted only when AKK should require one unique eligible idle pane. To answer an in-flight question, use agent_knock_knock_respond instead. For ordinary use add only request and omit monitoring timeouts unless the user explicitly asks to change them. timeoutSeconds is unsupported. AKK never starts a coding agent. This is asynchronous: after acceptance, yield and wait for the callback or a later explicit status request.",
                 parameters: sendParameters,
-                async execute(_toolCallId, params) {
-                    const result = await runSendRequest(api, isRecord(params) ? params : {}, toolContext);
+                async execute(toolCallId, params) {
+                    const result = await runSendRequest(api, isRecord(params) ? params : {}, toolContext, terminalMessageIdForToolCall({
+                        toolCallId,
+                        sessionKey: toolContext?.sessionKey,
+                        sessionId: toolContext?.sessionId,
+                        toolName: "agent_knock_knock_send"
+                    }));
                     return toolResult(result, { submissionErrors: true });
                 }
             }), { name: "agent_knock_knock_send", optional: true });
@@ -474,8 +463,9 @@ function createPlugin(relayPath) {
                 name: "agent_knock_knock_respond",
                 description: "Respond to a question or blocked callback in one exact in-flight AKK turn. This continues that turn and does not create a new turn; use agent_knock_knock_send with session_id for later ordinary work.",
                 parameters: respondParameters,
-                buildArgs: (params) => {
+                buildArgs: (params, toolContext, toolCallId) => {
                     const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
+                    const openclawSession = stringValue(toolContext?.sessionKey) ?? "agent:main:main";
                     const args = [
                         "respond",
                         "--turn",
@@ -483,7 +473,14 @@ function createPlugin(relayPath) {
                         "--message",
                         requiredString(params.request, "request")
                     ];
+                    pushOptional(args, "--message-id", terminalMessageIdForToolCall({
+                        toolCallId,
+                        sessionKey: openclawSession,
+                        sessionId: toolContext?.sessionId,
+                        toolName: "agent_knock_knock_respond"
+                    }));
                     pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
+                    pushOptional(args, "--openclaw-session", openclawSession);
                     return args;
                 }
             });
@@ -558,9 +555,89 @@ function createPlugin(relayPath) {
         }
     });
 }
+function createMonitorReconciliationService(api, configuredIntervalMs) {
+    const intervalMs = Number.isFinite(configuredIntervalMs) &&
+        configuredIntervalMs > 0
+        ? Math.max(50, Math.ceil(configuredIntervalMs))
+        : MONITOR_SUPERVISOR_INTERVAL_MS;
+    let stopped = true;
+    let timer;
+    let inFlight;
+    const reconciliationArgs = (reason) => {
+        const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
+        const args = ["reconcile-monitors", "--reason", reason];
+        if (reason === "monitor_supervision") {
+            args.push("--terminal-monitors-only");
+        }
+        pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
+        return args;
+    };
+    const report = (result, reason) => {
+        if (reason === "startup_reconciliation" ||
+            Number(result.launched ?? 0) > 0 ||
+            Number(result.errors ?? 0) > 0) {
+            const label = reason === "startup_reconciliation"
+                ? "monitor reconciliation"
+                : `monitor ${reason}`;
+            api.logger.info?.(`agent-knock-knock ${label}: ` +
+                `checked=${result.checked ?? 0} launched=${result.launched ?? 0} ` +
+                `already_running=${result.already_running ?? 0} skipped=${result.skipped ?? 0} ` +
+                `errors=${result.errors ?? 0}`);
+        }
+    };
+    const schedule = () => {
+        if (stopped) {
+            return;
+        }
+        timer = setTimeout(() => {
+            timer = undefined;
+            inFlight = supervise().finally(() => {
+                inFlight = undefined;
+                schedule();
+            });
+        }, intervalMs);
+        timer.unref?.();
+    };
+    const supervise = async () => {
+        try {
+            const result = await runCliAsync(api, reconciliationArgs("monitor_supervision"));
+            report(result, "monitor_supervision");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            api.logger.warn?.(`agent-knock-knock monitor supervision deferred after error: ${message}`);
+        }
+    };
+    return {
+        id: "agent-knock-knock-monitor-reconciliation",
+        start() {
+            if (!stopped) {
+                return;
+            }
+            stopped = false;
+            try {
+                const result = runCli(api, reconciliationArgs("startup_reconciliation"));
+                report(result, "startup_reconciliation");
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                api.logger.warn?.(`agent-knock-knock monitor reconciliation skipped after startup error: ${message}`);
+            }
+            schedule();
+        },
+        async stop() {
+            stopped = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            await inFlight;
+        }
+    };
+}
 const plugin = createPlugin(defaultBinPath);
-export function createOpenClawPluginForTest(relayPath) {
-    return createPlugin(relayPath);
+export function createOpenClawPluginForTest(relayPath, options = {}) {
+    return createPlugin(relayPath, options);
 }
 export default plugin;
 async function handleAkkCommand(api, ctx) {
@@ -647,7 +724,9 @@ async function handleAkkCommand(api, ctx) {
             case "send":
                 return {
                     text: formatSendCommandResult(result),
-                    isError: ["uncertain", "aborted"].includes(String(result.submission_outcome ?? "")) || result.status === "delivered_unfenced"
+                    isError: terminalSubmissionReported(result)
+                        ? !isAkkNativeSubmissionAccepted(result)
+                        : result.status === "delivered_unfenced"
                 };
             case "respond":
                 return formatAkkRespondCommandResult(result);
@@ -694,11 +773,30 @@ function formatDelegateCommandResult(result) {
         ].join("\n");
     }
     if (result.status === "submission_aborted") {
+        const safeToRetry = result.safe_to_retry === true && result.do_not_retry !== true;
         return [
             `AKK stopped before sending the terminal task to ${agent}.`,
             `session: ${sessionId}`,
             `turn: ${turnId}`,
-            "next: no tmux input was sent, so this request may be retried."
+            safeToRetry
+                ? "next: no tmux input was sent and the aborted receipt is durable, so this request may be retried."
+                : "next: do not retry automatically; AKK could not prove a durable safe abort, so inspect this Turn and its tmux dispatch ledger."
+        ].join("\n");
+    }
+    if (result.status === "submission_pending_acceptance") {
+        return [
+            `AKK dispatched terminal input to ${agent}, but native acceptance is still pending.`,
+            `session: ${sessionId}`,
+            `turn: ${turnId}`,
+            "next: do not retry or report success; wait for acceptance or inspect the shared tmux pane."
+        ].join("\n");
+    }
+    if (result.status === "submission_not_accepted") {
+        return [
+            `AKK proved that ${agent} did not accept the terminal draft.`,
+            `session: ${sessionId}`,
+            `turn: ${turnId}`,
+            "next: do not retry automatically; inspect the exact draft in the shared tmux pane."
         ].join("\n");
     }
     return [
@@ -843,12 +941,43 @@ function formatSendCommandResult(result) {
         ].join("\n");
     }
     if (result.submission_outcome === "aborted") {
+        const safeToRetry = result.safe_to_retry === true && result.do_not_retry !== true;
         return [
             "AKK terminal submission was aborted before tmux input.",
             `session: ${sessionId}`,
             `turn: ${turnId}`,
             `status: ${result.status ?? status}`,
-            "next: this request was not sent and may be retried."
+            safeToRetry
+                ? "next: this request was not sent, the aborted receipt is durable, and it may be retried."
+                : "next: do not retry automatically; inspect the Turn because a durable safe abort was not proven."
+        ].join("\n");
+    }
+    if (result.submission_outcome === "pending_acceptance") {
+        return [
+            "AKK dispatched the terminal input but native acceptance is still pending.",
+            `session: ${sessionId}`,
+            `turn: ${turnId}`,
+            `status: ${result.status ?? status}`,
+            "next: do not retry or report success; wait for acceptance or inspect the shared tmux pane."
+        ].join("\n");
+    }
+    if (result.submission_outcome === "not_accepted") {
+        return [
+            "AKK proved that the agent did not accept the terminal draft.",
+            `session: ${sessionId}`,
+            `turn: ${turnId}`,
+            `status: ${result.status ?? status}`,
+            "next: do not retry automatically; inspect the exact draft in the shared tmux pane."
+        ].join("\n");
+    }
+    if (terminalSubmissionReported(result) &&
+        !isAkkNativeSubmissionAccepted(result)) {
+        return [
+            "AKK could not verify native agent acceptance for this terminal input.",
+            `session: ${sessionId}`,
+            `turn: ${turnId}`,
+            `status: ${result.status ?? status}`,
+            "next: do not retry or report success; inspect the exact Turn receipt and shared tmux pane."
         ].join("\n");
     }
     const lines = [
@@ -977,7 +1106,7 @@ function terminalScreenExcerpt(result) {
         ? text
         : `…${text.slice(-1599)}`;
 }
-async function runSendRequest(api, params, toolContext) {
+async function runSendRequest(api, params, toolContext, messageId) {
     const requestedType = Object.hasOwn(params, "type")
         ? stringValue(params.type)
         : "task";
@@ -994,7 +1123,7 @@ async function runSendRequest(api, params, toolContext) {
         ? requiredString(params.selector, "selector")
         : undefined;
     if (!sessionId && !selector) {
-        return runDelegate(api, params, toolContext);
+        return runDelegate(api, { ...params, messageId }, toolContext);
     }
     const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
     const openclawSession = stringValue(toolContext?.sessionKey) ??
@@ -1010,6 +1139,7 @@ async function runSendRequest(api, params, toolContext) {
     }
     args.push("--message", requiredString(params.request, "request"), "--background");
     pushOptional(args, "--type", stringValue(params.type));
+    pushOptional(args, "--message-id", messageId);
     pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
     pushOptional(args, "--idle-timeout-minutes", numberString(params.idleTimeoutMinutes) ??
         numberString(config.idleTimeoutMinutes));
@@ -1046,14 +1176,24 @@ function isSubmissionError(result) {
     if (!isRecord(result)) {
         return false;
     }
+    if (terminalSubmissionReported(result)) {
+        return !isAkkNativeSubmissionAccepted(result);
+    }
     return [
         "submission_unfenced",
         "submission_uncertain",
-        "submission_aborted"
+        "submission_aborted",
+        "submission_pending_acceptance",
+        "submission_not_accepted"
     ].includes(String(result.status ?? "")) ||
-        ["uncertain", "aborted"].includes(String(result.submission_outcome ?? "")) ||
+        ["uncertain", "aborted", "pending_acceptance", "not_accepted"].includes(String(result.submission_outcome ?? "")) ||
         result.status === "delivered_unfenced";
 }
+function terminalSubmissionReported(result) {
+    return result.submission_outcome !== undefined ||
+        result.delivery_receipt !== undefined ||
+        result.delivered !== undefined;
+}
 function withTurnIdentity(result) {
     if (!isRecord(result)) {
         return result;
@@ -1126,6 +1266,7 @@ async function runDelegate(api, params, toolContext) {
         "--background"
     ];
     pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
+    pushOptional(args, "--message-id", stringValue(params.messageId));
     pushOptional(args, "--openclaw-session", openclawSession);
     pushOptional(args, "--gateway-method", CALLBACK_METHOD);
     pushOptional(args, "--gateway-session", openclawSession);
@@ -1159,6 +1300,14 @@ async function runDelegate(api, params, toolContext) {
         parsedPaths?.logPath;
     const submissionUncertain = parsed.submission_outcome === "uncertain";
     const submissionAborted = parsed.submission_outcome === "aborted";
+    const submissionAccepted = parsed.submission_outcome === "agent_accepted" &&
+        parsed.delivery_receipt === "agent_accepted" &&
+        parsed.delivered === true;
+    const submissionNotAccepted = parsed.submission_outcome === "not_accepted";
+    const submissionPending = !submissionAccepted &&
+        !submissionUncertain &&
+        !submissionAborted &&
+        !submissionNotAccepted;
     const submissionUnfenced = parsed.status === "delivered_unfenced";
     const agent = (isRecord(parsedConversation?.executor)
         ? stringValue(parsedConversation.executor.kind)
@@ -1171,14 +1320,22 @@ async function runDelegate(api, params, toolContext) {
                 ? "submission_uncertain"
                 : submissionAborted
                     ? "submission_aborted"
-                    : "async_pending",
+                    : submissionNotAccepted
+                        ? "submission_not_accepted"
+                        : submissionPending
+                            ? "submission_pending_acceptance"
+                            : "async_pending",
         submission_status: submissionUnfenced
             ? "submitted_unfenced"
             : submissionUncertain
                 ? "uncertain"
                 : submissionAborted
                     ? "aborted"
-                    : "accepted",
+                    : submissionNotAccepted
+                        ? "not_accepted"
+                        : submissionPending
+                            ? "pending_acceptance"
+                            : "accepted",
         conversation_id: conversationId,
         session_id: sessionId,
         turn_id: turnId,
@@ -1214,32 +1371,73 @@ async function runDelegate(api, params, toolContext) {
                     note: "AKK could not prove whether tmux accepted Enter. Do not retry automatically; inspect the exact AKK Turn record and shared terminal."
                 }
                 : submissionAborted
-                    ? {
-                        submission_outcome: "aborted",
-                        safe_to_retry: true,
-                        reason: parsed.reason,
-                        openclaw_next_action: parsed.openclaw_next_action,
-                        note: "AKK stopped before sending tmux input. The request was not submitted and may be retried."
-                    }
-                    : {
-                        openclaw_next_action: {
-                            action: "yield",
-                            reason: "The coding agent is working in the shared tmux terminal. End this OpenClaw turn now and wait for an Agent Knock Knock callback.",
-                            do_not: "Do not poll terminal internals while waiting. Further communication must use Agent Knock Knock tools so the same shared terminal remains authoritative.",
-                            expected_callback: "The callback will be injected and scheduled into this OpenClaw session by the agent-knock-knock.callback Gateway method."
-                        },
-                        note: "The task was sent to the shared tmux terminal. OpenClaw should yield now and wait for the scheduled callback turn."
-                    })
+                    ? parsed.safe_to_retry === true && parsed.do_not_retry !== true
+                        ? {
+                            submission_outcome: "aborted",
+                            safe_to_retry: true,
+                            do_not_retry: false,
+                            reason: parsed.reason,
+                            openclaw_next_action: parsed.openclaw_next_action,
+                            note: "AKK stopped before sending tmux input and durably proved a safe abort. The request may be retried."
+                        }
+                        : {
+                            submission_outcome: "aborted",
+                            safe_to_retry: false,
+                            do_not_retry: true,
+                            reason: parsed.reason,
+                            openclaw_next_action: parsed.openclaw_next_action,
+                            note: "AKK could not prove a durable safe abort. Do not retry automatically; inspect the exact Turn and terminal dispatch ledger."
+                        }
+                    : submissionNotAccepted
+                        ? {
+                            submission_outcome: "not_accepted",
+                            do_not_retry: true,
+                            reason: parsed.reason,
+                            openclaw_next_action: parsed.openclaw_next_action,
+                            note: "AKK proved terminal transport but the exact draft is still present in the agent composer. Do not retry automatically; inspect the shared pane."
+                        }
+                        : submissionPending
+                            ? {
+                                submission_outcome: "pending_acceptance",
+                                do_not_retry: true,
+                                reason: parsed.reason,
+                                openclaw_next_action: parsed.openclaw_next_action,
+                                note: "AKK proved only terminal transport and is still waiting for native agent acceptance. Do not retry or report the task as accepted."
+                            }
+                            : {
+                                openclaw_next_action: {
+                                    action: "yield",
+                                    reason: "The coding agent is working in the shared tmux terminal. End this OpenClaw turn now and wait for an Agent Knock Knock callback.",
+                                    do_not: "Do not poll terminal internals while waiting. Further communication must use Agent Knock Knock tools so the same shared terminal remains authoritative.",
+                                    expected_callback: "The callback will be injected and scheduled into this OpenClaw session by the agent-knock-knock.callback Gateway method."
+                                },
+                                note: "The task was sent to the shared tmux terminal. OpenClaw should yield now and wait for the scheduled callback turn."
+                            })
     };
 }
+function terminalMessageIdForToolCall({ toolCallId: toolCallIdValue, sessionKey: sessionKeyValue, sessionId: sessionIdValue, toolName }) {
+    const toolCallId = stringValue(toolCallIdValue);
+    if (!toolCallId) {
+        return undefined;
+    }
+    const sessionKey = stringValue(sessionKeyValue) ?? "agent:main:main";
+    // sessionId is the OpenClaw conversation incarnation. It changes across
+    // /new and /reset even when sessionKey remains stable. Keep a literal null
+    // fallback so retries with the same legacy context remain deterministic.
+    const sessionId = stringValue(sessionIdValue) ?? null;
+    const digest = createHash("sha256")
+        .update(JSON.stringify([sessionKey, sessionId, toolName, toolCallId]))
+        .digest("hex");
+    return `msg-openclaw-${digest}`;
+}
 function registerCliTool(api, { name, description, parameters, buildArgs, normalizeTurnIdentity = true, isErrorResult = (_result) => false }) {
     api.registerTool((toolContext) => ({
         label: toolLabel(name),
         name,
         description,
         parameters,
-        async execute(_toolCallId, params) {
-            const result = runCli(api, buildArgs(isRecord(params) ? params : {}, toolContext));
+        async execute(toolCallId, params) {
+            const result = runCli(api, buildArgs(isRecord(params) ? params : {}, toolContext, toolCallId));
             return toolResult(result, {
                 submissionErrors: name === "agent_knock_knock_respond",
                 normalizeTurnIdentity,