@scotthuang/agent-knock-knock 0.2.10 → 0.2.12

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" });
 }
@@ -3424,6 +3434,7 @@ function waitForPidsToExit(pids, timeoutMs) {
 function markConversationStalled({ statePath, logPath, reason, detail = {} }) {
     const releaseLock = acquireFileLock(`${statePath}.lock`);
     let stalledConversation;
+    let stalledMessage;
     try {
         const conversation = loadState(statePath);
         if (!isWaitingForAgent(conversation.status)) {
@@ -3435,11 +3446,31 @@ function markConversationStalled({ statePath, logPath, reason, detail = {} }) {
             return conversation;
         }
         const now = new Date().toISOString();
+        const executor = executorForConversation(conversation);
+        const shouldNotify = Boolean(conversation.gateway_method && !conversation.stalled_notification_sent_at);
+        stalledMessage = shouldNotify
+            ? createMessage({
+                conversation,
+                from: executor.actor,
+                to: "openclaw",
+                type: "error",
+                requiresResponse: false,
+                body: [
+                    `AKK marked this ${executor.display_name} task as stalled: ${reason}.`,
+                    "",
+                    `Conversation: ${conversation.conversation_id}`,
+                    `Session: ${executor.session}`,
+                    "Use `AKK status` for details, `AKK send` to retry/follow up, or `AKK close` to close it."
+                ].join("\n")
+            })
+            : undefined;
         stalledConversation = {
             ...conversation,
             status: "stalled",
             stalled_at: now,
             stalled_reason: reason,
+            stalled_notification_sent_at: shouldNotify ? now : conversation.stalled_notification_sent_at,
+            stalled_notification_message_id: stalledMessage?.id ?? conversation.stalled_notification_message_id,
             updated_at: now
         };
         saveState(statePath, stalledConversation);
@@ -3464,13 +3495,12 @@ function markConversationStalled({ statePath, logPath, reason, detail = {} }) {
     finally {
         releaseLock();
     }
-    if (stalledConversation) {
+    if (stalledConversation && stalledMessage) {
         deliverStalledNotification({
             statePath,
             logPath,
             conversation: stalledConversation,
-            reason,
-            detail
+            message: stalledMessage
         });
     }
     return stalledConversation;
@@ -3527,27 +3557,10 @@ function markConversationNeedsModelSelection({ statePath, logPath, reason, detai
     }
     return modelSelectionConversation;
 }
-function deliverStalledNotification({ statePath, logPath, conversation, reason, detail = {} }) {
+function deliverStalledNotification({ statePath, logPath, conversation, message }) {
     if (!conversation.gateway_method) {
         return;
     }
-    const executor = executorForConversation(conversation);
-    const trace = buildStalledTraceSummary({ conversation, logPath, detail });
-    const message = createMessage({
-        conversation,
-        from: executor.actor,
-        to: "openclaw",
-        type: "error",
-        requiresResponse: false,
-        body: [
-            `AKK marked this ${executor.display_name} task as stalled: ${reason}.`,
-            "",
-            `Conversation: ${conversation.conversation_id}`,
-            `Session: ${executor.session}`,
-            trace ? `Trace: ${trace}` : "",
-            "Use `AKK status` for details, `AKK send` to retry/follow up, or `AKK close` to close it."
-        ].filter(Boolean).join("\n")
-    });
     const gatewayToken = conversation.gateway_token;
     const gatewayUrl = gatewayToken ? conversation.gateway_url : undefined;
     const delivery = deliverToGatewayMethod({
@@ -3566,6 +3579,7 @@ function deliverStalledNotification({ statePath, logPath, conversation, reason,
         conversation_id: conversation.conversation_id,
         event: "stalled_gateway_method_delivery",
         method: conversation.gateway_method,
+        message_id: message.id,
         status: delivery.status,
         stdout: delivery.stdout,
         stderr: delivery.stderr
@@ -3573,6 +3587,7 @@ function deliverStalledNotification({ statePath, logPath, conversation, reason,
     runtimeLog("info", "stalled_gateway_method_delivery", {
         conversation_id: conversation.conversation_id,
         method: conversation.gateway_method,
+        message_id: message.id,
         status: delivery.status,
         failure_kind: classifyProcessFailure(delivery),
         stdout: textSummary(delivery.stdout),
@@ -3596,46 +3611,20 @@ function deliverStalledNotification({ statePath, logPath, conversation, reason,
         ts: new Date().toISOString(),
         conversation_id: conversation.conversation_id,
         event: "stalled_chat_send_delivery",
+        message_id: message.id,
         status: chatSendDelivery.status,
         stdout: chatSendDelivery.stdout,
         stderr: chatSendDelivery.stderr
     });
     runtimeLog("info", "stalled_chat_send_delivery", {
         conversation_id: conversation.conversation_id,
+        message_id: message.id,
         status: chatSendDelivery.status,
         failure_kind: classifyProcessFailure(chatSendDelivery),
         stdout: textSummary(chatSendDelivery.stdout),
         stderr: textSummary(chatSendDelivery.stderr)
     });
 }
-function buildStalledTraceSummary({ conversation, logPath, detail = {} }) {
-    const detailRecord = isRecord(detail) ? detail : {};
-    const outputPath = typeof detailRecord.output_path === "string"
-        ? detailRecord.output_path
-        : traceOutputPath({
-            conversation,
-            events: safeReadEvents(logPath),
-            logPath
-        });
-    if (!outputPath || !fs.existsSync(outputPath)) {
-        return undefined;
-    }
-    const output = fs.readFileSync(outputPath, "utf8").slice(-64 * 1024);
-    const parts = output
-        .split(/\r?\n/)
-        .map((line) => sanitizeTraceText(line.trim(), 220))
-        .filter((line) => line &&
-        !line.startsWith("input:") &&
-        !line.startsWith("output:") &&
-        !line.startsWith("{") &&
-        !line.startsWith("}") &&
-        !line.includes("--message-json"))
-        .slice(-6);
-    if (parts.length === 0) {
-        return undefined;
-    }
-    return cleanProcessText(parts.join(" | "))?.slice(0, 500);
-}
 function safeReadEvents(logPath) {
     try {
         return readNdjsonLog(logPath);
@@ -4059,8 +4048,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]