@scotthuang/agent-knock-knock 0.2.28 → 0.2.30

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.30 - 2026-07-09
+
+### Added
+
+- Added terminal bridge monitoring for tmux-controlled Codex conversations so AKK can send only the user-facing task text, observe Codex rollout/terminal state, and deliver the OpenClaw callback itself.
+
+## 0.2.29 - 2026-07-08
+
+### Fixed
+
+- Clarified AKK skill and `agent_knock_knock_send` tool routing so messages to listed AKK/Codex sessions, terminal-controlled rows, or tmux targets such as `my-work:0.1` use `send` instead of starting a new delegation.
+
 ## 0.2.28 - 2026-07-07
 
 ### Fixed

package/README.md

@@ -173,6 +173,7 @@ AKK list
 - `native`: local native sessions that AKK can discover but cannot directly control.
 - `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.
 - `terminal_controlled` entries can be addressed directly by their `id` from `AKK list` for `AKK send <id>`, `AKK status <id>`, `AKK cancel <id>`, and `AKK approve <id>`. They do not need an AKK state file before terminal control.
+- Background sends to terminal-controlled Codex sessions use terminal bridge mode: AKK types only the user-facing task text into the tmux pane, monitors Codex rollout/terminal state, and delivers the OpenClaw callback itself when it observes completion.
 - `AKK status <terminal-controlled-id>` is the unified way to inspect current terminal output. AKK captures the terminal pane internally and returns `terminal_screen`; there is no separate public screen-capture command.
 - `AKK describe <id>` summarizes what a listed session is about. AKK-managed sessions use saved conversation history; native and terminal-controlled Codex sessions use exact Codex rollout history when a session id is available, fall back to cwd-matched rollout history when needed, and otherwise report only visible terminal/process context with lower confidence.
 
@@ -283,7 +284,7 @@ Runtime logs are diagnostic-only and are safe to use for local troubleshooting.
 - Default agent: configured with `defaultAgent`; fallback is `codex`
 - OpenClaw session: inherited from the current OpenClaw session; fallback is `agent:main:main`
 - Delegated ACPX session: generated per new task, unless `session`, `codexSession`, `claudeSession`, or `cursorSession` is configured
-- Agent callback timeout: `60` minutes before a waiting task is marked `stalled`
+- Agent callback timeout: `60` minutes before a waiting task or terminal bridge monitor is marked `stalled`
 - Idle timeout: `10080` minutes before an idle task is lazily closed
 - Soft response limit: `50` rounds
 - Hard response limit: `100` rounds

package/dist/src/cli.js

@@ -124,7 +124,7 @@ async function runCommand(commandName, options) {
         runCallback(options);
     }
     else if (commandName === "monitor") {
-        runMonitor(options);
+        await runMonitor(options);
     }
     else if (commandName === "agent") {
         await runAgent(options);
@@ -875,7 +875,8 @@ function createNativeSessionConversation({ agent, strategy, session, modelInfo,
             model_source: modelInfo?.source,
             takeover_match_kind: takeoverMatchKind,
             terminal_control: terminalControl,
-            needs_bootstrap: needsBootstrap
+            needs_bootstrap: needsBootstrap,
+            terminal_bridge: strategy === "terminal_control"
         }
     }, paths);
     saveState(paths.statePath, attachedConversation);
@@ -1264,6 +1265,53 @@ function startExecutorMonitor({ statePath, logPath, pid, outputPath, agentTimeou
     child.unref();
     return child;
 }
+function startTerminalBridgeMonitor({ statePath, logPath, agentTimeoutMinutes, pollIntervalMs, codexHome }) {
+    const args = [
+        new URL(import.meta.url).pathname,
+        "monitor",
+        "--terminal-bridge",
+        "--state",
+        statePath,
+        "--log",
+        logPath,
+        "--agent-timeout-minutes",
+        String(agentTimeoutMinutes),
+        "--poll-interval-ms",
+        String(pollIntervalMs)
+    ];
+    if (codexHome) {
+        args.push("--codex-home", codexHome);
+    }
+    const child = spawn(process.execPath, args, {
+        detached: true,
+        stdio: "ignore",
+        cwd: process.cwd(),
+        env: process.env
+    });
+    child.unref();
+    return child;
+}
+function terminalBridgeEnabled(conversation) {
+    const nativeTakeover = isRecord(conversation.native_session_takeover)
+        ? conversation.native_session_takeover
+        : undefined;
+    return nativeTakeover?.["terminal_bridge"] === true;
+}
+function withTerminalBridgeState({ conversation, message, startedAt }) {
+    const nativeTakeover = isRecord(conversation.native_session_takeover)
+        ? conversation.native_session_takeover
+        : {};
+    return {
+        ...conversation,
+        native_session_takeover: {
+            ...nativeTakeover,
+            terminal_bridge: true,
+            terminal_bridge_started_at: startedAt,
+            terminal_bridge_message_id: message.id
+        },
+        updated_at: startedAt
+    };
+}
 function uniqueDelegateSessionName(kind) {
     const { sessionPrefix } = executorDefinitionForKind(kind || "claude");
     const timestamp = new Date().toISOString().replace(/\D/g, "").slice(0, 14);
@@ -2310,7 +2358,9 @@ async function runTerminalConversationSend({ options, conversationId, messageBod
 }
 async function runTerminalControlSend({ options, conversation, nextConversation, statePath, logPath, executor, message, terminalControl, needsNativeTakeoverBootstrap }) {
     const provider = createTerminalControlProvider(options);
-    const terminalPayload = needsNativeTakeoverBootstrap
+    const bridge = terminalBridgeEnabled(conversation);
+    const bridgeStartedAt = new Date().toISOString();
+    const terminalPayload = needsNativeTakeoverBootstrap && !bridge
         ? terminalSubmissionPayload(buildAgentSendPayload({
             conversation,
             executor,
@@ -2342,14 +2392,45 @@ async function runTerminalControlSend({ options, conversation, nextConversation,
         message: textSummary(message.body),
         payload: textSummary(terminalPayload)
     });
+    const bridgeConversation = bridge
+        ? withTerminalBridgeState({
+            conversation: nextConversation,
+            message,
+            startedAt: bridgeStartedAt
+        })
+        : nextConversation;
     const deliveredConversation = markTakeoverBootstrapped({
-        conversation: nextConversation,
+        conversation: bridgeConversation,
         statePath,
         logPath,
         executor,
-        native: needsNativeTakeoverBootstrap,
+        native: needsNativeTakeoverBootstrap && !bridge,
         fork: false
     });
+    const bridgeMonitor = bridge && deliveredConversation.gateway_method && options.disableTerminalBridgeMonitor !== true
+        ? startTerminalBridgeMonitor({
+            statePath,
+            logPath,
+            agentTimeoutMinutes: Number(options.agentTimeoutMinutes ?? DEFAULT_AGENT_TIMEOUT_MINUTES),
+            pollIntervalMs: Number(options.monitorPollIntervalMs ?? DEFAULT_MONITOR_POLL_INTERVAL_MS),
+            codexHome: options.codexHome
+        })
+        : undefined;
+    if (bridgeMonitor) {
+        appendEvent(logPath, {
+            ts: new Date().toISOString(),
+            conversation_id: deliveredConversation.conversation_id,
+            event: "terminal_bridge_monitor_launch",
+            pid: bridgeMonitor.pid ?? null,
+            terminal_control: terminalControl,
+            agent_timeout_minutes: Number(options.agentTimeoutMinutes ?? DEFAULT_AGENT_TIMEOUT_MINUTES)
+        });
+        runtimeLog("info", "terminal_bridge_monitor_launch", {
+            conversation_id: deliveredConversation.conversation_id,
+            monitor_pid: bridgeMonitor.pid ?? null,
+            terminal_target: terminalControl.target
+        });
+    }
     printJson({
         conversation: deliveredConversation,
         message,
@@ -2358,6 +2439,7 @@ async function runTerminalControlSend({ options, conversation, nextConversation,
         background: true,
         callback_expected: Boolean(deliveredConversation.callback_command || deliveredConversation.gateway_method),
         terminal_control: terminalControl,
+        monitor_pid: bridgeMonitor?.pid ?? null,
         executor,
         budget: budgetAction(deliveredConversation),
         openclaw_next_action: openClawYieldNextAction({
@@ -2423,7 +2505,8 @@ function createManagedTerminalConversationFromRawId({ options, conversationId, m
             attached_at: now.toISOString(),
             takeover_match_kind: "raw_terminal_send",
             terminal_control: terminalControl,
-            needs_bootstrap: true
+            needs_bootstrap: false,
+            terminal_bridge: true
         }
     }, paths);
     saveState(paths.statePath, attachedConversation);
@@ -3192,7 +3275,10 @@ function runClose(options) {
         closed: true
     });
 }
-function runMonitor(options) {
+async function runMonitor(options) {
+    if (options.terminalBridge) {
+        return await runTerminalBridgeMonitor(options);
+    }
     const statePath = expandHome(required(options.state, "--state is required"));
     const logPath = expandHome(options.log ?? logPathForStatePath(statePath));
     const pid = options.pid ? Number(options.pid) : undefined;
@@ -3321,6 +3407,227 @@ function runMonitor(options) {
         sleepSync(pollIntervalMs);
     }
 }
+async function runTerminalBridgeMonitor(options) {
+    const statePath = expandHome(required(options.state, "--state is required"));
+    const logPath = expandHome(options.log ?? logPathForStatePath(statePath));
+    const timeoutMinutes = Number(options.agentTimeoutMinutes ?? DEFAULT_AGENT_TIMEOUT_MINUTES);
+    const pollIntervalMs = Math.max(50, Number(options.pollIntervalMs ?? DEFAULT_MONITOR_POLL_INTERVAL_MS));
+    let conversation = loadState(statePath);
+    const executor = executorForConversation(conversation);
+    appendEvent(logPath, {
+        ts: new Date().toISOString(),
+        conversation_id: conversation.conversation_id,
+        event: "terminal_bridge_monitor_started",
+        executor,
+        agent_timeout_minutes: timeoutMinutes,
+        poll_interval_ms: pollIntervalMs
+    });
+    runtimeLog("info", "terminal_bridge_monitor_started", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        executor_session: executor.session,
+        agent_timeout_minutes: timeoutMinutes
+    });
+    while (true) {
+        conversation = loadState(statePath);
+        if (!isWaitingForAgent(conversation.status)) {
+            runtimeLog("info", "terminal_bridge_monitor_finished", {
+                conversation_id: conversation.conversation_id,
+                status: conversation.status,
+                reason: "conversation_no_longer_waiting"
+            });
+            printJson({
+                conversation,
+                monitored: true,
+                terminal_bridge: true,
+                completed: false,
+                reason: "conversation_no_longer_waiting"
+            });
+            return;
+        }
+        const nativeTakeover = isRecord(conversation.native_session_takeover)
+            ? conversation.native_session_takeover
+            : undefined;
+        const terminalControl = terminalControlFromTakeover(nativeTakeover);
+        if (!terminalControl || nativeTakeover?.["terminal_bridge"] !== true) {
+            const stalledConversation = markConversationStalled({
+                statePath,
+                logPath,
+                reason: "terminal bridge monitor could not find terminal bridge metadata",
+                detail: {
+                    terminal_bridge: true
+                }
+            });
+            printJson({
+                conversation: stalledConversation,
+                monitored: true,
+                terminal_bridge: true,
+                stalled: true,
+                reason: stalledConversation?.stalled_reason
+            });
+            return;
+        }
+        const terminalStatus = await terminalStatusForControl(terminalControl, options);
+        const approval = terminalStatus.approval_state;
+        if (isRecord(approval) && approval.blocked === true) {
+            appendEvent(logPath, {
+                ts: new Date().toISOString(),
+                conversation_id: conversation.conversation_id,
+                event: "terminal_bridge_approval_detected",
+                terminal_control: terminalControl,
+                activity_state: terminalStatus.activity_state,
+                activity_reason: terminalStatus.activity_reason
+            });
+            printJson({
+                conversation,
+                monitored: true,
+                terminal_bridge: true,
+                awaiting_approval: true,
+                terminal_control: terminalControl,
+                terminal_status: terminalStatus
+            });
+            return;
+        }
+        const contextMatch = await terminalBridgeCodexContext({
+            conversation,
+            nativeTakeover,
+            options
+        });
+        const startedAt = stringValue(nativeTakeover?.["terminal_bridge_started_at"]);
+        const assistantMessage = contextMatch?.context
+            ? latestAssistantAfter(contextMatch.context, startedAt)
+            : undefined;
+        const terminalStillWorking = terminalStatus.activity_state === "working";
+        if (assistantMessage && !terminalStillWorking) {
+            appendEvent(logPath, {
+                ts: new Date().toISOString(),
+                conversation_id: conversation.conversation_id,
+                event: "terminal_bridge_completion_detected",
+                terminal_control: terminalControl,
+                match: contextMatch?.match,
+                codex_session: contextMatch?.context.source,
+                assistant_timestamp: assistantMessage.timestamp
+            });
+            const callbackMessage = createMessage({
+                conversation,
+                from: executor.actor,
+                to: "openclaw",
+                type: "done",
+                requiresResponse: false,
+                body: assistantMessage.text,
+                metadata: {
+                    source: "terminal_bridge",
+                    terminal_control: terminalControl,
+                    codex_session: contextMatch?.context.source,
+                    confidence: contextMatch?.confidence,
+                    assistant_timestamp: assistantMessage.timestamp
+                }
+            });
+            runLockedCallback({
+                ...options,
+                statePath,
+                log: logPath,
+                messageJson: JSON.stringify(callbackMessage),
+                gatewayMethod: conversation.gateway_method,
+                gatewaySession: conversation.gateway_session,
+                openclawSession: conversation.openclaw_session,
+                openclawBin: conversation.openclaw_bin,
+                gatewayUrl: conversation.gateway_url,
+                token: conversation.gateway_token
+            });
+            return;
+        }
+        if (Number.isFinite(timeoutMinutes) && timeoutMinutes > 0) {
+            const updatedAtMs = Date.parse(String(conversation.updated_at ?? conversation.created_at));
+            if (Number.isFinite(updatedAtMs) && Date.now() - updatedAtMs >= timeoutMinutes * 60 * 1000) {
+                const stalledConversation = markConversationStalled({
+                    statePath,
+                    logPath,
+                    reason: `terminal bridge did not observe completion after ${timeoutMinutes} minutes`,
+                    detail: {
+                        terminal_bridge: true,
+                        terminal_control: terminalControl,
+                        match: contextMatch?.match,
+                        terminal_activity_state: terminalStatus.activity_state
+                    }
+                });
+                printJson({
+                    conversation: stalledConversation,
+                    monitored: true,
+                    terminal_bridge: true,
+                    stalled: true,
+                    reason: stalledConversation?.stalled_reason
+                });
+                return;
+            }
+        }
+        sleepSync(pollIntervalMs);
+    }
+}
+async function terminalBridgeCodexContext({ conversation, nativeTakeover, options }) {
+    const provider = createAgentSessionProvider("codex", options);
+    const nativeSessionId = stringValue(nativeTakeover?.["native_session_id"]);
+    const terminalConversation = parseTerminalConversationId(nativeSessionId);
+    const activeProcess = await activeCodexProcessForPid(options, terminalConversation?.pid);
+    const directSessionId = activeProcess?.sessionId ?? (terminalConversation ? undefined : nativeSessionId);
+    if (directSessionId) {
+        const context = await provider.getForkContext({
+            sessionId: directSessionId,
+            maxMessages: Number(options.maxMessages ?? 16),
+            maxCommands: Number(options.maxCommands ?? 10),
+            maxTextLength: Number(options.maxTextLength ?? 4000)
+        });
+        if (context) {
+            return {
+                context,
+                process: activeProcess,
+                match: activeProcess?.sessionId ? "process_session_id" : "native_session_id",
+                confidence: "high"
+            };
+        }
+    }
+    const cwd = activeProcess?.cwd ?? stringValue(nativeTakeover?.["source_cwd"]);
+    if (!cwd) {
+        return undefined;
+    }
+    const sessions = (await provider.listHistoricalSessions())
+        .filter((session) => session.cwd === cwd)
+        .sort((left, right) => Number(right.updatedAtMs ?? 0) - Number(left.updatedAtMs ?? 0));
+    const selected = sessions[0];
+    if (!selected) {
+        return undefined;
+    }
+    const context = await provider.getForkContext({
+        sessionId: selected.id,
+        maxMessages: Number(options.maxMessages ?? 16),
+        maxCommands: Number(options.maxCommands ?? 10),
+        maxTextLength: Number(options.maxTextLength ?? 4000)
+    });
+    if (!context) {
+        return undefined;
+    }
+    return {
+        context,
+        process: activeProcess,
+        match: sessions.length === 1 ? "cwd" : "cwd_latest",
+        confidence: sessions.length === 1 ? "medium" : "low"
+    };
+}
+function latestAssistantAfter(context, startedAt) {
+    const threshold = startedAt ? Date.parse(startedAt) : undefined;
+    return [...visibleRolloutMessages(context)]
+        .reverse()
+        .find((message) => {
+        if (message.role !== "assistant") {
+            return false;
+        }
+        if (!Number.isFinite(threshold)) {
+            return true;
+        }
+        const messageTime = message.timestamp ? Date.parse(message.timestamp) : NaN;
+        return Number.isFinite(messageTime) && messageTime >= Number(threshold);
+    });
+}
 function resolveExecutable(command) {
     if (command.includes(path.sep)) {
         return command;