@scotthuang/agent-knock-knock 0.2.10 → 0.2.11

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.11 - 2026-06-25
+
+### Added
+
+- Added terminal-controlled `AKK cancel` support by sending Control-C to the controlled tmux pane.
+- Added structured terminal reachability, screen, and approval state to `AKK status` for terminal-controlled sessions.
+
+### Removed
+
+- Removed the public `agent discover` CLI path and `agent_knock_knock_agent_discover` OpenClaw tool; use `AKK list` for active/local session visibility.
+- Removed the legacy `safe_resume` takeover strategy; native takeover now uses active process-based terminate, terminal-control, or fork paths.
+
 ## 0.2.10 - 2026-06-25
 
 ### Fixed

package/README.md

@@ -117,9 +117,13 @@ AKK Codex: review the current branch and propose a small fix
 AKK Claude: review the latest commit
 AKK Cursor: fix the flaky UI test
 akk list
+akk status <conversation-id>
 akk send <conversation-id>: continue with the smaller implementation
 akk cancel <conversation-id>
+akk recover <conversation-id>
 akk close <conversation-id>
+AKK terminal takeover Codex <native-session-id>
+AKK approve <conversation-id>
 ```
 
 Surfaces that support OpenClaw native commands can use the same workflow through `/akk`:
@@ -154,32 +158,23 @@ Optional default-agent config:
 
 ## Native Codex Takeover
 
-Experimental: AKK can discover and take over Codex CLI sessions that were started outside AKK. This is useful when you started Codex in a terminal, left the machine, and want OpenClaw to continue managing that work from chat.
+Experimental: AKK can list and take over Codex CLI sessions that were started outside AKK. This is useful when you started Codex in a terminal, left the machine, and want OpenClaw to continue managing that work from chat.
 
 List current AKK-managed and local agent work:
 
 ```text
 AKK list
-AKK Codex active
 ```
 
 `AKK list` returns separate groups for:
 
 - `delegated`: AKK-managed background tasks.
 - `native`: local native sessions that AKK can discover but cannot directly control.
-- `terminal_controlled`: local sessions running in a controllable terminal provider such as tmux. These entries include terminal metadata, command capabilities, and concise approval state when a visible approval prompt is detected.
-
-Lower-level discovery prompts remain available for historical session and capability inspection:
-
-```text
-AKK Codex sessions
-AKK Codex capabilities
-```
+- `terminal_controlled`: local sessions running in a controllable terminal provider. The current provider is tmux. These entries include terminal metadata, command capabilities, and concise approval state when a visible approval prompt is detected.
 
 Takeover prompts:
 
 ```text
-AKK safe resume Codex <native-session-id>
 AKK takeover Codex <native-session-id>
 AKK terminal takeover Codex <native-session-id>
 AKK fork takeover Codex <native-session-id>
@@ -188,9 +183,8 @@ AKK approve <conversation-id>
 
 Strategies:
 
-- `safe resume`: attach a stopped/inactive Codex session to AKK.
 - `takeover`: stop an active matching Codex CLI after explicit confirmation, then resume it under AKK.
-- `terminal takeover`: attach an active Codex CLI running inside tmux after explicit confirmation. AKK sends follow-ups directly to the tmux pane and can approve the currently visible Codex approval prompt.
+- `terminal takeover`: attach an active Codex CLI running inside a controllable terminal provider after explicit confirmation. AKK sends follow-ups directly to the terminal pane, can send Control-C for cancel, and can approve the currently visible Codex approval prompt.
 - `fork takeover`: keep the original Codex CLI running, ask OpenClaw to summarize bounded source context, then create a new AKK-managed fork from that summary.
 
 For long-running local Codex sessions that you may want OpenClaw to operate from WeChat, run Codex inside tmux. AKK does not require tmux, but tmux enables terminal-control takeover without stopping the original process:

package/dist/src/cli.js

@@ -13,7 +13,7 @@ import { executorBootstrapPrompt } from "./bootstrap.js";
 import { writeRuntimeLog } from "./runtime-log.js";
 import { formatTranscript, readNdjsonLog } from "./transcript.js";
 import { appendEvent, defaultStoreDir, listConversations, logPathForStatePath, loadConversationById, loadState, messageEvent, pathsForConversation, pathsForConversationDir, saveState, statePathForConversationId } from "./store.js";
-import { planFork, planSafeResume, planTakeover } from "./session-takeover-planner.js";
+import { planFork, planTakeover } from "./session-takeover-planner.js";
 import { StaticTerminalControlProvider, TmuxTerminalControlProvider, enrichActiveProcessesWithTerminalControl } from "./terminal-control-provider.js";
 const DEFAULT_IDLE_TIMEOUT_MINUTES = 10080;
 const DEFAULT_AGENT_TIMEOUT_MINUTES = 60;
@@ -99,7 +99,7 @@ async function runCommand(commandName, options) {
         await runApprove(options);
     }
     else if (commandName === "cancel") {
-        runCancel(options);
+        await runCancel(options);
     }
     else if (commandName === "recover") {
         runRecover(options);
@@ -210,47 +210,13 @@ function runDoctor(options) {
     });
 }
 async function runAgent(options) {
-    const agentCommand = required(options.agentCommand, "agent subcommand is required: discover or takeover");
-    if (agentCommand === "discover") {
-        printJson(await runAgentDiscover(options));
-        return;
-    }
+    const agentCommand = required(options.agentCommand, "agent subcommand is required: takeover");
     if (agentCommand === "takeover") {
         printJson(await runAgentTakeover(options));
         return;
     }
     throw new Error(`unsupported agent subcommand: ${agentCommand}`);
 }
-async function runAgentDiscover(options) {
-    const agent = required(options.agent, "--agent is required");
-    const scope = required(options.scope, "--scope is required");
-    const provider = createAgentSessionProvider(agent, options);
-    const capabilities = await provider.getCapabilities();
-    if (scope === "capabilities") {
-        return {
-            agent,
-            scope,
-            capabilities
-        };
-    }
-    if (scope === "sessions") {
-        return {
-            agent,
-            scope,
-            capabilities,
-            sessions: await provider.listHistoricalSessions()
-        };
-    }
-    if (scope === "active") {
-        return {
-            agent,
-            scope,
-            capabilities,
-            active: await listActiveSessionsWithTerminalControl(provider, options)
-        };
-    }
-    throw new Error(`unsupported discover scope: ${scope}`);
-}
 async function runAgentTakeover(options) {
     const agent = required(options.agent, "--agent is required");
     const sessionId = required(options.sessionId, "--session-id is required");
@@ -270,36 +236,6 @@ async function runAgentTakeover(options) {
             }
         };
     }
-    if (strategy === "safe_resume") {
-        const plan = planSafeResume(session, await listActiveSessionsWithTerminalControl(provider, options));
-        if (plan.allowed && options.createConversation) {
-            const modelInfo = await provider.getSessionModel(session.id);
-            const attached = createNativeSessionConversation({
-                agent,
-                strategy,
-                session,
-                modelInfo,
-                options
-            });
-            return {
-                agent,
-                sessionId,
-                strategy,
-                status: "attached",
-                sideEffectsExecuted: true,
-                plan,
-                ...attached
-            };
-        }
-        return {
-            agent,
-            sessionId,
-            strategy,
-            status: plan.allowed ? "ready" : "blocked",
-            sideEffectsExecuted: false,
-            plan
-        };
-    }
     if (strategy === "terminate_then_resume") {
         const activeSessions = await listActiveSessionsWithTerminalControl(provider, options);
         const plan = planTakeover(session, activeSessions);
@@ -402,7 +338,7 @@ async function runAgentTakeover(options) {
                     plan,
                     error: {
                         code: "terminal_target_unavailable",
-                        message: `No matching tmux-controlled Codex process was found for ${terminalTarget}`
+                        message: `No matching terminal-controlled Codex process was found for ${terminalTarget}`
                     }
                 };
             }
@@ -1419,7 +1355,6 @@ function nativeListEntry(session, activeSessions) {
         confidence: session.confidence,
         reason: session.reason,
         commands: {
-            safe_resume: Boolean(session.sessionId),
             terminate_then_resume: true,
             fork: Boolean(session.sessionId),
             terminal_control_attach: false,
@@ -1458,7 +1393,7 @@ async function terminalControlledListEntry(session, activeSessions, options) {
             capture_screen: true,
             approve: approvalState.approvable === true,
             status: true,
-            cancel: false,
+            cancel: true,
             close: false
         }
     };
@@ -1540,21 +1475,8 @@ async function runStatus(options) {
     const terminalControl = terminalControlFromTakeover(isRecord(conversation.native_session_takeover) ? conversation.native_session_takeover : undefined);
     if (terminalControl) {
         result.terminal_control = terminalControl;
-        try {
-            const screen = await createTerminalControlProvider(options).capture(terminalControl.target, {
-                scrollbackLines: Number(options.scrollbackLines ?? 120),
-                socketPath: terminalControl.socketPath
-            });
-            result.terminal_screen = {
-                excerpt: screenExcerpt(screen),
-                approval: detectCodexApprovalPrompt(screen)
-            };
-        }
-        catch (error) {
-            result.terminal_screen = {
-                error: error instanceof Error ? error.message : String(error)
-            };
-        }
+        result.terminal_status = await terminalStatusForControl(terminalControl, options);
+        result.terminal_screen = result.terminal_status.screen;
     }
     printJson(result);
     runtimeLog("info", "task_status_read", {
@@ -1566,6 +1488,48 @@ async function runStatus(options) {
         trace: Boolean(options.trace)
     });
 }
+async function terminalStatusForControl(terminalControl, options) {
+    try {
+        const screen = await createTerminalControlProvider(options).capture(terminalControl.target, {
+            scrollbackLines: Number(options.scrollbackLines ?? 120),
+            socketPath: terminalControl.socketPath
+        });
+        const approval = detectCodexApprovalPrompt(screen);
+        const blocked = isCodexApprovalPromptVisible(screen);
+        return {
+            provider: terminalControl.kind,
+            target: terminalControl.target,
+            reachable: true,
+            approval_state: {
+                scanned: true,
+                blocked,
+                approvable: approval.approvable,
+                key: approval.approvable ? approval.key : undefined,
+                label: approval.approvable ? approval.label : undefined,
+                reason: approval.approvable ? undefined : approval.reason
+            },
+            screen: {
+                excerpt: screenExcerpt(screen),
+                approval
+            }
+        };
+    }
+    catch (error) {
+        return {
+            provider: terminalControl.kind,
+            target: terminalControl.target,
+            reachable: false,
+            approval_state: {
+                scanned: false,
+                blocked: false,
+                approvable: false
+            },
+            screen: {
+                error: error instanceof Error ? error.message : String(error)
+            }
+        };
+    }
+}
 async function runSend(options) {
     const messageBody = required(options.message ?? options.request, "--message is required");
     cleanupIdleConversations(storeDirFromOptions(options), options);
@@ -2370,12 +2334,26 @@ function markConversationNeedsRecovery({ conversation, statePath, logPath, execu
         budget: budgetAction(nextConversation)
     };
 }
-function runCancel(options) {
+async function runCancel(options) {
     cleanupIdleConversations(storeDirFromOptions(options), options);
     const { conversation, statePath, logPath } = loadConversationFromOptions(options);
     if (["closed", "cancelled"].includes(conversation.status)) {
         throw new Error(`cannot cancel ${conversation.conversation_id}; conversation is ${conversation.status}`);
     }
+    const nativeTakeover = isRecord(conversation.native_session_takeover)
+        ? conversation.native_session_takeover
+        : undefined;
+    const terminalControl = terminalControlFromTakeover(nativeTakeover);
+    if (terminalControl) {
+        await runTerminalControlCancel({
+            options,
+            conversation,
+            statePath,
+            logPath,
+            terminalControl
+        });
+        return;
+    }
     const executor = executorForConversation(conversation);
     const acpxPath = resolveExecutable("acpx");
     const executorEnv = environmentForExecutor(executor, {
@@ -2434,6 +2412,38 @@ function runCancel(options) {
         budget: budgetAction(nextConversation)
     });
 }
+async function runTerminalControlCancel({ options, conversation, statePath, logPath, terminalControl }) {
+    const provider = createTerminalControlProvider(options);
+    await provider.sendKeys(terminalControl.target, ["C-c"], {
+        socketPath: terminalControl.socketPath
+    });
+    const now = new Date().toISOString();
+    appendEvent(logPath, {
+        ts: now,
+        conversation_id: conversation.conversation_id,
+        event: "terminal_cancel_requested",
+        terminal_control: terminalControl,
+        key: "C-c"
+    });
+    runtimeLog("info", "terminal_cancel_requested", {
+        conversation_id: conversation.conversation_id,
+        terminal_target: terminalControl.target,
+        key: "C-c"
+    });
+    const nextConversation = {
+        ...conversation,
+        terminal_cancel_requested_at: now,
+        updated_at: now
+    };
+    saveState(statePath, nextConversation);
+    printJson({
+        conversation: nextConversation,
+        cancel_requested: true,
+        terminal_control: terminalControl,
+        key: "C-c",
+        budget: budgetAction(nextConversation)
+    });
+}
 function runRecover(options) {
     runRecoveryDecision({ ...options, mode: "recover" });
 }
@@ -4059,8 +4069,7 @@ function usage() {
   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
-  agent-knock-knock agent discover --agent codex --scope capabilities|sessions|active
-  agent-knock-knock agent takeover --agent codex --session-id <id> --strategy safe_resume|terminate_then_resume|terminal_control|fork [--create-conversation]
+  agent-knock-knock agent takeover --agent codex --session-id <id> --strategy terminate_then_resume|terminal_control|fork [--create-conversation]
   agent-knock-knock callback --state <file> --message-json <json> [--record-only]
   agent-knock-knock transcript --log <file> [--include-raw]
   agent-knock-knock transcript --conversation <dir> [--include-raw]