@scotthuang/agent-knock-knock 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.2.5 - 2026-06-25
+
+### Added
+
+- Added grouped `AKK list` output for `delegated`, `native`, and `terminal_controlled` sessions while preserving the legacy `tasks` field.
+- Added terminal-controlled approval state to `AKK list`, allowing tmux-backed Codex sessions to show when an approval prompt is visible and approvable.
+
+### Changed
+
+- Updated OpenClaw routing guidance so active/native Codex session questions use `AKK list` instead of the separate native discover tool.
+
+## 0.2.4 - 2026-06-24
+
+### Fixed
+
+- Added tmux socket fallback discovery for OpenClaw Gateway environments whose service `TMPDIR` differs from the user's interactive terminal, allowing active discovery to mark tmux-controlled Codex panes reliably.
+- Preserved the discovered tmux socket path through terminal-control takeover, status, send, and approve operations so follow-up terminal actions use the same tmux server.
+
 ## 0.2.3 - 2026-06-24
 
 ### Fixed

package/README.md

@@ -156,11 +156,23 @@ Optional default-agent config:
 
 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.
 
-Discovery prompts:
+List current AKK-managed and local agent work:
 
 ```text
-AKK Codex sessions
+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
 ```
 

package/dist/src/cli.js

@@ -87,7 +87,7 @@ async function runCommand(commandName, options) {
         runDelegate(options);
     }
     else if (commandName === "list") {
-        runList(options);
+        await runList(options);
     }
     else if (commandName === "status") {
         await runStatus(options);
@@ -645,17 +645,12 @@ function terminalControlFromTakeover(nativeTakeover) {
         panePid,
         currentCommand: stringValue(terminalControl.currentCommand),
         currentPath: stringValue(terminalControl.currentPath),
+        socketPath: stringValue(terminalControl.socketPath),
         capabilities: ["capture_screen", "send_keys", "terminal_approval"]
     };
 }
 function detectCodexApprovalPrompt(screen) {
-    const approvalMarkers = [
-        "Would you like to run the following command?",
-        "Would you like to make the following edits?",
-        "Would you like to grant these permissions?",
-        "needs your approval."
-    ];
-    if (!approvalMarkers.some((marker) => screen.includes(marker))) {
+    if (!isCodexApprovalPromptVisible(screen)) {
         return {
             approvable: false,
             reason: "no Codex approval prompt was detected in the terminal screen"
@@ -684,6 +679,15 @@ function detectCodexApprovalPrompt(screen) {
         reason: "no primary approve option with a shortcut was detected"
     };
 }
+function isCodexApprovalPromptVisible(screen) {
+    const approvalMarkers = [
+        "Would you like to run the following command?",
+        "Would you like to make the following edits?",
+        "Would you like to grant these permissions?",
+        "needs your approval."
+    ];
+    return approvalMarkers.some((marker) => screen.includes(marker));
+}
 function screenExcerpt(screen, maxLength = 4000) {
     const lines = screen.trimEnd().split(/\r?\n/);
     return lines.slice(Math.max(0, lines.length - 80)).join("\n").slice(-maxLength);
@@ -1266,7 +1270,7 @@ function environmentForExecutor(executor, options = {}) {
         all_proxy: proxy
     };
 }
-function runList(options) {
+async function runList(options) {
     const storeDir = expandHome(options.storeDir ?? options.logDir ?? defaultStoreDir(process.cwd()));
     const cleanup = cleanupIdleConversations(storeDir, options);
     const includeAll = Boolean(options.all);
@@ -1277,20 +1281,235 @@ function runList(options) {
         .filter((conversation) => includeAll || isActiveStatus(conversation.status))
         .filter((conversation) => !agentFilter || conversation.agent === agentFilter)
         .filter((conversation) => !statusFilter || conversation.status === statusFilter);
+    const delegated = conversations.map(delegatedListEntry);
+    const nativeScan = await buildNativeListGroups({ options, agentFilter, statusFilter });
     printJson({
         store_dir: storeDir,
         cleanup,
+        delegated,
+        native: nativeScan.native,
+        terminal_controlled: nativeScan.terminalControlled,
+        native_scan: nativeScan.summary,
         tasks: conversations
     });
     runtimeLog("info", "tasks_listed", {
         store_dir: storeDir,
         returned_count: conversations.length,
+        native_count: nativeScan.native.length,
+        terminal_controlled_count: nativeScan.terminalControlled.length,
+        native_scan_error: nativeScan.summary.error,
         include_all: includeAll,
         agent_filter: agentFilter,
         status_filter: statusFilter,
         cleanup
     });
 }
+async function buildNativeListGroups({ options, agentFilter, statusFilter }) {
+    const empty = {
+        native: [],
+        terminalControlled: [],
+        summary: {
+            enabled: false,
+            agents: [],
+            error: undefined
+        }
+    };
+    if (options.managedOnly) {
+        return empty;
+    }
+    if (statusFilter && statusFilter !== "active") {
+        return {
+            ...empty,
+            summary: {
+                enabled: false,
+                agents: [],
+                skipped: `native active discovery skipped for status filter ${statusFilter}`
+            }
+        };
+    }
+    if (agentFilter && agentFilter !== "codex") {
+        return {
+            ...empty,
+            summary: {
+                enabled: true,
+                agents: [],
+                skipped: `native active discovery is not implemented for ${agentFilter}`
+            }
+        };
+    }
+    try {
+        const provider = createAgentSessionProvider("codex", options);
+        const activeSessions = await listActiveSessionsWithTerminalControl(provider, options);
+        const rootSessions = rootActiveProcesses(activeSessions);
+        const terminalControlled = [];
+        const native = [];
+        for (const session of rootSessions) {
+            if (session.terminalControl) {
+                terminalControlled.push(await terminalControlledListEntry(session, activeSessions, options));
+            }
+            else {
+                native.push(nativeListEntry(session, activeSessions));
+            }
+        }
+        return {
+            native,
+            terminalControlled,
+            summary: {
+                enabled: true,
+                agents: ["codex"],
+                active_count: activeSessions.length,
+                native_count: native.length,
+                terminal_controlled_count: terminalControlled.length,
+                approval_scan: options.noApprovalScan ? "disabled" : "enabled"
+            }
+        };
+    }
+    catch (error) {
+        return {
+            native: [],
+            terminalControlled: [],
+            summary: {
+                enabled: true,
+                agents: ["codex"],
+                error: error instanceof Error ? error.message : String(error)
+            }
+        };
+    }
+}
+function delegatedListEntry(task) {
+    return {
+        ...task,
+        id: task.conversation_id,
+        source: "akk_delegate",
+        commands: {
+            send: canSendDelegated(task.status),
+            cancel: isWaitingForAgent(task.status),
+            close: task.status !== "closed",
+            status: true,
+            approve: false,
+            capture_screen: false
+        }
+    };
+}
+function nativeListEntry(session, activeSessions) {
+    return {
+        id: `native:codex:${session.pid}`,
+        source: "native_active",
+        agent: "codex",
+        status: "active",
+        pid: session.pid,
+        child_pids: childPidsForRoot(session, activeSessions),
+        command: session.command,
+        cwd: session.cwd,
+        workspace: session.cwd,
+        elapsed: session.elapsed,
+        session_id: session.sessionId,
+        confidence: session.confidence,
+        reason: session.reason,
+        commands: {
+            safe_resume: Boolean(session.sessionId),
+            terminate_then_resume: true,
+            fork: Boolean(session.sessionId),
+            terminal_control_attach: false,
+            send: false,
+            cancel: false,
+            approve: false,
+            close: false,
+            status: false
+        }
+    };
+}
+async function terminalControlledListEntry(session, activeSessions, options) {
+    const terminalControl = session.terminalControl;
+    if (!terminalControl) {
+        throw new Error(`process ${session.pid} is not terminal-controlled`);
+    }
+    const approvalState = await approvalStateForTerminal(terminalControl, options);
+    return {
+        id: `terminal:${terminalControl.kind}:${terminalControl.target}:${session.pid}`,
+        source: "terminal_control",
+        agent: "codex",
+        status: "active",
+        pid: session.pid,
+        child_pids: childPidsForRoot(session, activeSessions),
+        command: session.command,
+        cwd: session.cwd,
+        workspace: session.cwd,
+        elapsed: session.elapsed,
+        session_id: session.sessionId,
+        confidence: session.confidence,
+        reason: session.reason,
+        terminal_control: terminalControl,
+        approval_state: approvalState,
+        commands: {
+            send: true,
+            capture_screen: true,
+            approve: approvalState.approvable === true,
+            status: true,
+            cancel: false,
+            close: false
+        }
+    };
+}
+async function approvalStateForTerminal(terminalControl, options) {
+    if (options.noApprovalScan) {
+        return {
+            scanned: false,
+            blocked: false,
+            approvable: false,
+            reason: "approval scan disabled"
+        };
+    }
+    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 {
+            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: blocked ? screenExcerpt(screen, 1000) : undefined
+        };
+    }
+    catch (error) {
+        return {
+            scanned: false,
+            blocked: false,
+            approvable: false,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+function rootActiveProcesses(processes) {
+    const pids = new Set(processes.map((process) => process.pid));
+    const roots = processes.filter((process) => !process.ppid || !pids.has(process.ppid));
+    const seenTerminalTargets = new Set();
+    return roots.filter((process) => {
+        const terminalTarget = process.terminalControl?.target;
+        if (!terminalTarget) {
+            return true;
+        }
+        if (seenTerminalTargets.has(terminalTarget)) {
+            return false;
+        }
+        seenTerminalTargets.add(terminalTarget);
+        return true;
+    });
+}
+function childPidsForRoot(root, processes) {
+    return processes
+        .filter((process) => process.ppid === root.pid)
+        .map((process) => process.pid);
+}
+function canSendDelegated(status) {
+    return !["failed", "closed", "cancelled"].includes(status);
+}
 async function runStatus(options) {
     cleanupIdleConversations(storeDirFromOptions(options), options);
     const { conversation, statePath, logPath } = loadConversationFromOptions(options);
@@ -1311,7 +1530,8 @@ async function runStatus(options) {
         result.terminal_control = terminalControl;
         try {
             const screen = await createTerminalControlProvider(options).capture(terminalControl.target, {
-                scrollbackLines: Number(options.scrollbackLines ?? 120)
+                scrollbackLines: Number(options.scrollbackLines ?? 120),
+                socketPath: terminalControl.socketPath
             });
             result.terminal_screen = {
                 excerpt: screenExcerpt(screen),
@@ -1694,7 +1914,8 @@ async function runApprove(options) {
     }
     const provider = createTerminalControlProvider(options);
     const screen = await provider.capture(terminalControl.target, {
-        scrollbackLines: Number(options.scrollbackLines ?? 120)
+        scrollbackLines: Number(options.scrollbackLines ?? 120),
+        socketPath: terminalControl.socketPath
     });
     const approval = detectCodexApprovalPrompt(screen);
     if (!approval.approvable) {
@@ -1708,7 +1929,9 @@ async function runApprove(options) {
         });
         return;
     }
-    await provider.sendKeys(terminalControl.target, [approval.key]);
+    await provider.sendKeys(terminalControl.target, [approval.key], {
+        socketPath: terminalControl.socketPath
+    });
     appendEvent(logPath, {
         ts: new Date().toISOString(),
         conversation_id: conversation.conversation_id,
@@ -1737,8 +1960,12 @@ async function runApprove(options) {
 }
 async function runTerminalControlSend({ options, conversation, nextConversation, statePath, logPath, executor, message, terminalControl, needsNativeTakeoverBootstrap }) {
     const provider = createTerminalControlProvider(options);
-    await provider.sendText(terminalControl.target, String(message.body ?? ""));
-    await provider.sendKeys(terminalControl.target, ["Enter"]);
+    await provider.sendText(terminalControl.target, String(message.body ?? ""), {
+        socketPath: terminalControl.socketPath
+    });
+    await provider.sendKeys(terminalControl.target, ["Enter"], {
+        socketPath: terminalControl.socketPath
+    });
     appendEvent(logPath, {
         ts: new Date().toISOString(),
         conversation_id: conversation.conversation_id,
@@ -3811,7 +4038,7 @@ function usage() {
   agent-knock-knock record --state <file> --message-json <json>
   agent-knock-knock bootstrap-prompt --callback-command <command> [--agent ${agentList}]
   agent-knock-knock delegate --request <text> [--agent ${agentList}] [--store-dir <dir>] [--all-proxy <url>] [--agent-timeout-minutes <minutes>] [--token <gateway-token>] [--send|--background]
-  agent-knock-knock list [--store-dir <dir>] [--agent ${agentList}] [--status <status>] [--all]
+  agent-knock-knock list [--store-dir <dir>] [--agent ${agentList}] [--status <status>] [--all] [--managed-only] [--no-approval-scan]
   agent-knock-knock status --conversation <id> [--store-dir <dir>] [--trace]
   agent-knock-knock send --conversation <id> --message <text> [--type answer|task|control] [--all-proxy <url>] [--agent-timeout-minutes <minutes>]
   agent-knock-knock approve --conversation <id>