@scotthuang/agent-knock-knock 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,8 +1,11 @@
 # Changelog
 
-## Unreleased
+## 0.2.1 - 2026-06-22
 
-No unreleased changes.
+### Changed
+
+- Deprecated the standalone restart recovery path from the OpenClaw-facing tool, slash command, skill, and docs. Conversations that need recovery now present `recover`, `close`, or starting a new independent delegation.
+- Changed `send` to automatically fall back to AKK replay recovery when the previous ACPX session is unavailable. Explicit recovery decisions remain available only through `--recovery-policy explicit`.
 
 ## 0.2.0 - 2026-06-22
 

package/README.md

@@ -140,7 +140,6 @@ akk list
 akk send <conversation-id>: continue with the smaller implementation
 akk cancel <conversation-id>
 akk recover <conversation-id>
-akk restart <conversation-id>
 akk close <conversation-id>
 ```
 
@@ -156,7 +155,6 @@ The plugin also registers the `/akk` slash command for channel surfaces that sup
 /akk send <conversation-id> <message>
 /akk cancel <conversation-id>
 /akk recover <conversation-id>
-/akk restart <conversation-id>
 /akk close <conversation-id> [reason]
 ```
 
@@ -172,7 +170,6 @@ If your OpenClaw config uses a restrictive tool allowlist, allow the tool:
       "agent_knock_knock_send",
       "agent_knock_knock_cancel",
       "agent_knock_knock_recover",
-      "agent_knock_knock_restart",
       "agent_knock_knock_close"
     ]
   }
@@ -189,13 +186,15 @@ New delegations create a fresh ACPX session by default, using a name like `akk-c
 
 Background launches also start a small AKK monitor process. The monitor exits when the conversation receives a callback or otherwise leaves the agent-waiting state. If the executor process disappears before a callback, or if no callback arrives before `agentTimeoutMinutes`, the conversation is marked `stalled` and AKK attempts to notify the original OpenClaw session through the callback Gateway route. The default agent timeout is 60 minutes.
 
-Some coding agents may not reliably resume a named ACPX session after their backing process disappears. Executors can opt into an explicit recovery decision flow. In that mode, a failed follow-up send marks the AKK conversation `needs_recovery` instead of automatically replaying history or starting a new session. The user can then choose:
+Some coding agents may not reliably resume a named ACPX session after their backing process disappears. By default, `AKK send <conversation-id>: <message>` automatically falls back to AKK replay recovery: it starts a fresh ACPX session, gives the agent a bounded summary of AKK's saved protocol history, and includes the pending message. The result includes `auto_recovered: true` when this happens.
+
+If a caller uses the explicit recovery policy, or if automatic recovery cannot complete, the AKK conversation can enter `needs_recovery`. The user can then choose:
 
 - `AKK recover <conversation-id>`: start a new coding-agent session with AKK's saved protocol history summary plus the pending message.
-- `AKK restart <conversation-id>`: start a new coding-agent session with only the pending message.
 - `AKK close <conversation-id>`: close the AKK task without recovery.
+- Start a new independent AKK delegation if the old task should not be recovered.
 
-Codex and Claude Code currently use native named-session recovery through ACPX. Cursor uses the explicit decision flow because its native session resume can be unreliable after the backing process disappears.
+Recover is AKK replay recovery, not guaranteed native coding-agent session resume. Codex, Claude Code, and Cursor all use the same default `send` auto-recovery behavior when the existing ACPX session is unavailable.
 
 Task status can include a safe executor trace with `--trace` or the OpenClaw status tool's `trace: true` parameter. Trace summaries show client lifecycle events, tool call names and statuses, permission-request markers, monitor events, and short sanitized output previews. Agent thinking content is never returned; it is counted and marked as redacted.
 
@@ -256,14 +255,11 @@ node dist/src/cli.js cancel \
   --conversation <conversation-id>
 ```
 
-Recover or restart a task that is waiting for an explicit recovery decision:
+Recover a task that is waiting for an explicit recovery decision:
 
 ```bash
 node dist/src/cli.js recover \
   --conversation <conversation-id>
-
-node dist/src/cli.js restart \
-  --conversation <conversation-id>
 ```
 
 Inspect and take over native Codex sessions that were started outside AKK:

package/dist/src/cli.js

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
 import { CodexLocalSessionProvider } from "./codex-local-session-provider.js";
 import { CodexStoreAdapter } from "./codex-store-adapter.js";
 import { applyMessageToConversation, budgetAction, createConversation, createMessage, executorForConversation, extractStructuredMessage, parseMessageJson, resolveExecutor } from "./protocol.js";
-import { EXECUTOR_KINDS, acpxCommandForExecutor, executorDefinitionForKind, modelEnvForExecutor, normalizeModelForExecutor, proxyEnvForExecutor, sessionRecoveryStrategyForExecutor } from "./executors.js";
+import { EXECUTOR_KINDS, acpxCommandForExecutor, executorDefinitionForKind, modelEnvForExecutor, normalizeModelForExecutor, proxyEnvForExecutor } from "./executors.js";
 import { executorBootstrapPrompt } from "./bootstrap.js";
 import { writeRuntimeLog } from "./runtime-log.js";
 import { formatTranscript, readNdjsonLog } from "./transcript.js";
@@ -100,9 +100,6 @@ async function runCommand(commandName, options) {
     else if (commandName === "recover") {
         runRecover(options);
     }
-    else if (commandName === "restart") {
-        runRestart(options);
-    }
     else if (commandName === "close") {
         runClose(options);
     }
@@ -1154,7 +1151,7 @@ function runSend(options) {
         throw new Error(`cannot send to ${conversation.conversation_id}; conversation is ${conversation.status}`);
     }
     if (conversation.status === "needs_recovery") {
-        throw new Error(`cannot send to ${conversation.conversation_id}; choose recover, restart, or close first`);
+        throw new Error(`cannot send to ${conversation.conversation_id}; choose recover, close, or delegate a new task first`);
     }
     if (conversation.status === "needs_model_selection" && !options.model) {
         throw new Error(`cannot send to ${conversation.conversation_id}; choose a supported model with --model first`);
@@ -1264,7 +1261,7 @@ function runSend(options) {
         stderr: textSummary(cleanProcessText(ensureSession.stderr))
     });
     if (ensureSession.error) {
-        if (requiresExplicitRecoveryDecision(executor, options)) {
+        if (requiresExplicitRecoveryDecision(options)) {
             printJson(markConversationNeedsRecovery({
                 conversation: nextConversation,
                 statePath,
@@ -1277,10 +1274,22 @@ function runSend(options) {
             }));
             return;
         }
-        throw new Error(`acpx ${executor.kind} session ensure failed to start: ${ensureSession.error.message}`);
+        autoRecoverSendFailure({
+            options,
+            conversation: nextConversation,
+            statePath,
+            logPath,
+            executor,
+            message,
+            failedStage: "session_ensure",
+            result: ensureSession,
+            reason: `acpx ${executor.kind} session ensure failed to start: ${ensureSession.error.message}`
+        });
+        return;
     }
     if (ensureSession.status !== 0) {
-        if (requiresExplicitRecoveryDecision(executor, options)) {
+        const reason = cleanProcessText(ensureSession.stderr || ensureSession.stdout || `acpx ${executor.kind} sessions ensure exited with status ${ensureSession.status}`);
+        if (requiresExplicitRecoveryDecision(options)) {
             printJson(markConversationNeedsRecovery({
                 conversation: nextConversation,
                 statePath,
@@ -1289,11 +1298,22 @@ function runSend(options) {
                 message,
                 failedStage: "session_ensure",
                 result: ensureSession,
-                reason: cleanProcessText(ensureSession.stderr || ensureSession.stdout || `acpx ${executor.kind} sessions ensure exited with status ${ensureSession.status}`)
+                reason
             }));
             return;
         }
-        throw new Error(cleanProcessText(ensureSession.stderr || ensureSession.stdout || `acpx ${executor.kind} sessions ensure exited with status ${ensureSession.status}`));
+        autoRecoverSendFailure({
+            options,
+            conversation: nextConversation,
+            statePath,
+            logPath,
+            executor,
+            message,
+            failedStage: "session_ensure",
+            result: ensureSession,
+            reason
+        });
+        return;
     }
     const acpxArgs = buildAcpxPromptArgs({ executor, payload, model: executorModel });
     if (options.background) {
@@ -1386,7 +1406,7 @@ function runSend(options) {
         stderr: textSummary(cleanProcessText(sendResult.stderr))
     });
     if (sendResult.error) {
-        if (requiresExplicitRecoveryDecision(executor, options)) {
+        if (requiresExplicitRecoveryDecision(options)) {
             printJson(markConversationNeedsRecovery({
                 conversation: nextConversation,
                 statePath,
@@ -1399,10 +1419,22 @@ function runSend(options) {
             }));
             return;
         }
-        throw new Error(`acpx ${executor.kind} send failed to start: ${sendResult.error.message}`);
+        autoRecoverSendFailure({
+            options,
+            conversation: nextConversation,
+            statePath,
+            logPath,
+            executor,
+            message,
+            failedStage: "message_send",
+            result: sendResult,
+            reason: `acpx ${executor.kind} send failed to start: ${sendResult.error.message}`
+        });
+        return;
     }
     if (sendResult.status !== 0) {
-        if (requiresExplicitRecoveryDecision(executor, options)) {
+        const reason = cleanProcessText(sendResult.stderr || sendResult.stdout || `acpx ${executor.kind} send exited with status ${sendResult.status}`);
+        if (requiresExplicitRecoveryDecision(options)) {
             printJson(markConversationNeedsRecovery({
                 conversation: nextConversation,
                 statePath,
@@ -1411,11 +1443,22 @@ function runSend(options) {
                 message,
                 failedStage: "message_send",
                 result: sendResult,
-                reason: cleanProcessText(sendResult.stderr || sendResult.stdout || `acpx ${executor.kind} send exited with status ${sendResult.status}`)
+                reason
             }));
             return;
         }
-        throw new Error(cleanProcessText(sendResult.stderr || sendResult.stdout || `acpx ${executor.kind} send exited with status ${sendResult.status}`));
+        autoRecoverSendFailure({
+            options,
+            conversation: nextConversation,
+            statePath,
+            logPath,
+            executor,
+            message,
+            failedStage: "message_send",
+            result: sendResult,
+            reason
+        });
+        return;
     }
     const deliveredConversation = markTakeoverBootstrapped({
         conversation: nextConversation,
@@ -1715,11 +1758,35 @@ function markForkSessionBootstrapped({ conversation, statePath, logPath, executo
     });
     return nextConversation;
 }
-function requiresExplicitRecoveryDecision(executor, options = {}) {
+function requiresExplicitRecoveryDecision(options = {}) {
     if (options.recoveryPolicy === "explicit" || options.recoveryPolicy === "explicit-decision") {
         return true;
     }
-    return sessionRecoveryStrategyForExecutor(executor) === "explicit-decision";
+    return false;
+}
+function autoRecoverSendFailure({ options, conversation, statePath, logPath, executor, message, failedStage, result, reason }) {
+    markConversationNeedsRecovery({
+        conversation,
+        statePath,
+        logPath,
+        executor,
+        message,
+        failedStage,
+        result,
+        reason
+    });
+    runtimeLog("info", "conversation_auto_recovery_start", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        failed_stage: failedStage,
+        reason: textSummary(reason)
+    });
+    runRecoveryDecision({
+        ...options,
+        mode: "recover",
+        autoRecovered: true
+    });
 }
 function markConversationNeedsRecovery({ conversation, statePath, logPath, executor, message, failedStage, result, reason }) {
     const now = new Date().toISOString();
@@ -1733,7 +1800,7 @@ function markConversationNeedsRecovery({ conversation, statePath, logPath, execu
         failed_message_id: message.id,
         pending_message: message,
         previous_executor: executor,
-        options: ["recover", "restart", "close"]
+        options: ["recover", "close", "delegate"]
     };
     const nextConversation = {
         ...conversation,
@@ -1837,9 +1904,6 @@ function runCancel(options) {
 function runRecover(options) {
     runRecoveryDecision({ ...options, mode: "recover" });
 }
-function runRestart(options) {
-    runRecoveryDecision({ ...options, mode: "restart" });
-}
 function runRecoveryDecision(options) {
     cleanupIdleConversations(storeDirFromOptions(options), options);
     const { conversation, statePath, logPath } = loadConversationFromOptions(options);
@@ -1871,9 +1935,7 @@ function runRecoveryDecision(options) {
         updated_at: now
     };
     saveState(statePath, recoveredConversation);
-    const payload = options.mode === "recover"
-        ? buildRecoverPayload({ conversation, pendingMessage, logPath })
-        : buildRestartPayload({ pendingMessage });
+    const payload = buildRecoverPayload({ conversation, pendingMessage, logPath });
     const acpxPath = resolveExecutable("acpx");
     const executorEnv = environmentForExecutor(executor, {
         allProxy: options.allProxy ?? conversation.executor_all_proxy
@@ -1935,8 +1997,8 @@ function runRecoveryDecision(options) {
         });
         printJson({
             conversation: recoveredConversation,
-            recovered: options.mode === "recover",
-            restarted: options.mode === "restart",
+            recovered: true,
+            auto_recovered: Boolean(options.autoRecovered),
             background: true,
             pid: child.pid ?? null,
             monitor_pid: monitor.pid ?? null,
@@ -1970,8 +2032,8 @@ function runRecoveryDecision(options) {
     }
     printJson({
         conversation: recoveredConversation,
-        recovered: options.mode === "recover",
-        restarted: options.mode === "restart",
+        recovered: true,
+        auto_recovered: Boolean(options.autoRecovered),
         delivered: true,
         executor,
         budget: budgetAction(recoveredConversation)
@@ -1994,16 +2056,6 @@ function buildRecoverPayload({ conversation, pendingMessage, logPath }) {
         JSON.stringify(pendingMessage)
     ].join("\n");
 }
-function buildRestartPayload({ pendingMessage }) {
-    return [
-        "Restart this Agent Knock Knock task in a new ACPX session.",
-        "Do not assume the previous coding-agent session context is available.",
-        "Follow only the pending OpenClaw message below.",
-        "Continue to report back only through the callback command already provided for this conversation.",
-        "",
-        JSON.stringify(pendingMessage)
-    ].join("\n");
-}
 function formatProtocolHistoryForRecovery(events) {
     const lines = events
         .filter((event) => event.event === "message")
@@ -3467,7 +3519,6 @@ function usage() {
   agent-knock-knock send --conversation <id> --message <text> [--type answer|task|control] [--all-proxy <url>] [--agent-timeout-minutes <minutes>]
   agent-knock-knock cancel --conversation <id> [--all-proxy <url>]
   agent-knock-knock recover --conversation <id> [--session <name>] [--all-proxy <url>]
-  agent-knock-knock restart --conversation <id> [--session <name>] [--all-proxy <url>]
   agent-knock-knock close --conversation <id> [--reason <text>]
   agent-knock-knock install-openclaw [--openclaw-bin <path>] [--skill-path <path>] [--no-restart]
   agent-knock-knock doctor