@scotthuang/agent-knock-knock 0.2.1 → 0.2.2

package/dist/src/cli.js

@@ -14,6 +14,7 @@ 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 { StaticTerminalControlProvider, TmuxTerminalControlProvider, enrichActiveProcessesWithTerminalControl } from "./terminal-control-provider.js";
 const DEFAULT_IDLE_TIMEOUT_MINUTES = 10080;
 const DEFAULT_AGENT_TIMEOUT_MINUTES = 60;
 const DEFAULT_MONITOR_POLL_INTERVAL_MS = 5000;
@@ -89,10 +90,13 @@ async function runCommand(commandName, options) {
         runList(options);
     }
     else if (commandName === "status") {
-        runStatus(options);
+        await runStatus(options);
     }
     else if (commandName === "send") {
-        runSend(options);
+        await runSend(options);
+    }
+    else if (commandName === "approve") {
+        await runApprove(options);
     }
     else if (commandName === "cancel") {
         runCancel(options);
@@ -242,7 +246,7 @@ async function runAgentDiscover(options) {
             agent,
             scope,
             capabilities,
-            active: await provider.listActiveSessions()
+            active: await listActiveSessionsWithTerminalControl(provider, options)
         };
     }
     throw new Error(`unsupported discover scope: ${scope}`);
@@ -267,7 +271,7 @@ async function runAgentTakeover(options) {
         };
     }
     if (strategy === "safe_resume") {
-        const plan = planSafeResume(session, await provider.listActiveSessions());
+        const plan = planSafeResume(session, await listActiveSessionsWithTerminalControl(provider, options));
         if (plan.allowed && options.createConversation) {
             const modelInfo = await provider.getSessionModel(session.id);
             const attached = createNativeSessionConversation({
@@ -297,7 +301,7 @@ async function runAgentTakeover(options) {
         };
     }
     if (strategy === "terminate_then_resume") {
-        const activeSessions = await provider.listActiveSessions();
+        const activeSessions = await listActiveSessionsWithTerminalControl(provider, options);
         const plan = planTakeover(session, activeSessions);
         if (options.confirmTerminate === true) {
             const expectedPid = Number(required(options.expectedPid, "--expected-pid is required with --confirm-terminate"));
@@ -332,7 +336,7 @@ async function runAgentTakeover(options) {
             const termination = terminateProcessTarget(target, {
                 timeoutMs: Number(options.terminateTimeoutMs ?? 3000)
             });
-            const activeAfterTermination = await provider.listActiveSessions();
+            const activeAfterTermination = await listActiveSessionsWithTerminalControl(provider, options);
             const afterTerminationPlan = planTakeover(session, activeAfterTermination);
             if (afterTerminationPlan.targets.some((candidate) => candidate.sessionId === session.id || candidate.pid === expectedPid)) {
                 return {
@@ -379,6 +383,60 @@ async function runAgentTakeover(options) {
             plan
         };
     }
+    if (strategy === "terminal_control") {
+        const activeSessions = await listActiveSessionsWithTerminalControl(provider, options);
+        const plan = planTerminalControlTakeover(session, activeSessions);
+        if (options.confirmTerminal === true) {
+            const terminalTarget = String(required(options.terminalTarget, "--terminal-target is required with --confirm-terminal"));
+            if (!options.createConversation) {
+                throw new Error("--create-conversation is required with --confirm-terminal");
+            }
+            const target = plan.targets.find((candidate) => candidate.terminalControl?.target === terminalTarget);
+            if (!plan.allowed || !target?.terminalControl) {
+                return {
+                    agent,
+                    sessionId,
+                    strategy,
+                    status: "blocked",
+                    sideEffectsExecuted: false,
+                    plan,
+                    error: {
+                        code: "terminal_target_unavailable",
+                        message: `No matching tmux-controlled Codex process was found for ${terminalTarget}`
+                    }
+                };
+            }
+            const modelInfo = await provider.getSessionModel(session.id);
+            const attached = createNativeSessionConversation({
+                agent,
+                strategy,
+                session,
+                modelInfo,
+                options,
+                takeoverMatchKind: "terminal_control",
+                terminalControl: target.terminalControl,
+                needsBootstrap: false
+            });
+            return {
+                agent,
+                sessionId,
+                strategy,
+                status: "attached",
+                sideEffectsExecuted: true,
+                plan,
+                terminalControl: target.terminalControl,
+                ...attached
+            };
+        }
+        return {
+            agent,
+            sessionId,
+            strategy,
+            status: plan.allowed ? "requires_confirmation" : "blocked",
+            sideEffectsExecuted: false,
+            plan
+        };
+    }
     if (strategy === "fork") {
         const contextPackage = await provider.getForkContext({
             sessionId,
@@ -516,6 +574,120 @@ function selectTerminateTarget({ plan, session, activeSessions, expectedPid, all
         matchKind: "cwd_only_confirmed"
     };
 }
+async function listActiveSessionsWithTerminalControl(provider, options) {
+    const activeSessions = await provider.listActiveSessions();
+    return enrichActiveProcessesWithTerminalControl(activeSessions, createTerminalControlProvider(options));
+}
+function createTerminalControlProvider(options) {
+    if (options.terminalsJson || options.terminalScreensJson) {
+        return new StaticTerminalControlProvider({
+            panes: parseJsonOption(options.terminalsJson, "--terminals-json"),
+            screens: parseJsonOption(options.terminalScreensJson, "--terminal-screens-json")
+        });
+    }
+    return new TmuxTerminalControlProvider();
+}
+function planTerminalControlTakeover(session, activeSessions) {
+    const matched = activeSessions
+        .filter((process) => process.kind === "codex_cli" &&
+        process.terminalControl &&
+        (process.sessionId === session.id ||
+            (!process.sessionId && process.cwd === session.cwd)));
+    const matchedPidSet = new Set(matched.map((process) => process.pid));
+    const targets = matched
+        .filter((process) => !process.ppid || !matchedPidSet.has(process.ppid))
+        .map((process) => ({
+        pid: process.pid,
+        childPids: matched
+            .filter((child) => child.ppid === process.pid)
+            .map((child) => child.pid),
+        cwd: process.cwd,
+        command: process.command,
+        sessionId: process.sessionId,
+        terminalControl: process.terminalControl
+    }));
+    const exactTargets = targets.filter((target) => target.sessionId === session.id);
+    const selectableTargets = exactTargets.length > 0 ? exactTargets : targets;
+    return {
+        mode: "terminal_control",
+        allowed: selectableTargets.length === 1,
+        requiresConfirmation: selectableTargets.length === 1,
+        reason: selectableTargets.length === 0
+            ? "no_terminal_control_target"
+            : selectableTargets.length === 1
+                ? "terminal_control_available"
+                : "ambiguous_terminal_control_target",
+        targets: selectableTargets
+    };
+}
+function terminalControlFromTakeover(nativeTakeover) {
+    if (!isRecord(nativeTakeover)) {
+        return undefined;
+    }
+    const terminalControl = nativeTakeover["terminal_control"];
+    if (!isRecord(terminalControl) || terminalControl.kind !== "tmux") {
+        return undefined;
+    }
+    const target = stringValue(terminalControl.target);
+    const session = stringValue(terminalControl.session);
+    const window = Number(terminalControl.window);
+    const pane = Number(terminalControl.pane);
+    const panePid = Number(terminalControl.panePid);
+    if (!target || !session || !Number.isInteger(window) || !Number.isInteger(pane) || !Number.isInteger(panePid)) {
+        return undefined;
+    }
+    return {
+        kind: "tmux",
+        target,
+        session,
+        window,
+        pane,
+        panePid,
+        currentCommand: stringValue(terminalControl.currentCommand),
+        currentPath: stringValue(terminalControl.currentPath),
+        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))) {
+        return {
+            approvable: false,
+            reason: "no Codex approval prompt was detected in the terminal screen"
+        };
+    }
+    for (const line of screen.split(/\r?\n/)) {
+        const match = /^[\s›]*1\.\s+(Yes,[^(]+)\(([^)]+)\)/u.exec(line.trim());
+        if (!match) {
+            continue;
+        }
+        const key = match[2].trim();
+        if (key !== "y") {
+            return {
+                approvable: false,
+                reason: `primary approval shortcut is ${key}, not y`
+            };
+        }
+        return {
+            approvable: true,
+            key,
+            label: match[1].trim()
+        };
+    }
+    return {
+        approvable: false,
+        reason: "no primary approve option with a shortcut was detected"
+    };
+}
+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);
+}
 function createForkConversation({ agent, strategy, session, contextPackage, forkSummary, modelInfo, options }) {
     const workspace = session.cwd;
     const storeDir = expandHome(options.storeDir ?? options.logDir ?? defaultStoreDir(workspace));
@@ -609,7 +781,7 @@ function createForkConversation({ agent, strategy, session, contextPackage, fork
         next: `Use AKK send ${forkedConversation.conversation_id}: <message> to start the forked ${agent} session with the approved summary.`
     };
 }
-function createNativeSessionConversation({ agent, strategy, session, modelInfo, options, takeoverMatchKind = strategy }) {
+function createNativeSessionConversation({ agent, strategy, session, modelInfo, options, takeoverMatchKind = strategy, terminalControl = undefined, needsBootstrap = true }) {
     const workspace = session.cwd;
     const storeDir = expandHome(options.storeDir ?? options.logDir ?? defaultStoreDir(workspace));
     cleanupIdleConversations(storeDir, options);
@@ -666,7 +838,8 @@ function createNativeSessionConversation({ agent, strategy, session, modelInfo,
             acpx_model: modelInfo?.acpxModel,
             model_source: modelInfo?.source,
             takeover_match_kind: takeoverMatchKind,
-            needs_bootstrap: true
+            terminal_control: terminalControl,
+            needs_bootstrap: needsBootstrap
         }
     }, paths);
     saveState(paths.statePath, attachedConversation);
@@ -1118,7 +1291,7 @@ function runList(options) {
         cleanup
     });
 }
-function runStatus(options) {
+async function runStatus(options) {
     cleanupIdleConversations(storeDirFromOptions(options), options);
     const { conversation, statePath, logPath } = loadConversationFromOptions(options);
     const events = readExistingEvents(logPath);
@@ -1133,6 +1306,24 @@ function runStatus(options) {
     if (options.trace) {
         result.trace = buildConversationTrace({ conversation, events, logPath });
     }
+    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)
+            });
+            result.terminal_screen = {
+                excerpt: screenExcerpt(screen),
+                approval: detectCodexApprovalPrompt(screen)
+            };
+        }
+        catch (error) {
+            result.terminal_screen = {
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
     printJson(result);
     runtimeLog("info", "task_status_read", {
         conversation_id: conversation.conversation_id,
@@ -1143,7 +1334,7 @@ function runStatus(options) {
         trace: Boolean(options.trace)
     });
 }
-function runSend(options) {
+async function runSend(options) {
     const messageBody = required(options.message ?? options.request, "--message is required");
     cleanupIdleConversations(storeDirFromOptions(options), options);
     const { conversation, statePath, logPath } = loadConversationFromOptions(options);
@@ -1215,6 +1406,21 @@ function runSend(options) {
         includeForkTakeoverBootstrap: needsForkTakeoverBootstrap,
         forkTakeover: forkTakeoverForSend
     });
+    const terminalControlForSend = terminalControlFromTakeover(nativeTakeoverForSend);
+    if (terminalControlForSend) {
+        await runTerminalControlSend({
+            options,
+            conversation,
+            nextConversation,
+            statePath,
+            logPath,
+            executor,
+            message,
+            terminalControl: terminalControlForSend,
+            needsNativeTakeoverBootstrap
+        });
+        return;
+    }
     if (nativeTakeoverForSend?.["native_session_id"] && executor.kind === "codex") {
         runNativeCodexResumeSend({
             options,
@@ -1476,6 +1682,94 @@ function runSend(options) {
         budget: budgetAction(deliveredConversation)
     });
 }
+async function runApprove(options) {
+    cleanupIdleConversations(storeDirFromOptions(options), options);
+    const { conversation, statePath, logPath } = loadConversationFromOptions(options);
+    const nativeTakeover = isRecord(conversation.native_session_takeover)
+        ? conversation.native_session_takeover
+        : undefined;
+    const terminalControl = terminalControlFromTakeover(nativeTakeover);
+    if (!terminalControl) {
+        throw new Error(`conversation ${conversation.conversation_id} is not controlled through a terminal`);
+    }
+    const provider = createTerminalControlProvider(options);
+    const screen = await provider.capture(terminalControl.target, {
+        scrollbackLines: Number(options.scrollbackLines ?? 120)
+    });
+    const approval = detectCodexApprovalPrompt(screen);
+    if (!approval.approvable) {
+        printJson({
+            conversation,
+            approved: false,
+            blocked: true,
+            reason: approval.reason,
+            terminal_control: terminalControl,
+            screen_excerpt: screenExcerpt(screen)
+        });
+        return;
+    }
+    await provider.sendKeys(terminalControl.target, [approval.key]);
+    appendEvent(logPath, {
+        ts: new Date().toISOString(),
+        conversation_id: conversation.conversation_id,
+        event: "terminal_approval_send",
+        terminal_control: terminalControl,
+        key: approval.key,
+        label: approval.label
+    });
+    runtimeLog("info", "terminal_approval_send", {
+        conversation_id: conversation.conversation_id,
+        terminal_target: terminalControl.target,
+        key: approval.key,
+        label: approval.label
+    });
+    saveState(statePath, {
+        ...conversation,
+        updated_at: new Date().toISOString()
+    });
+    printJson({
+        conversation,
+        approved: true,
+        terminal_control: terminalControl,
+        key: approval.key,
+        label: approval.label
+    });
+}
+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"]);
+    appendEvent(logPath, {
+        ts: new Date().toISOString(),
+        conversation_id: conversation.conversation_id,
+        event: "terminal_message_send",
+        executor,
+        terminal_control: terminalControl,
+        message: textSummary(message.body)
+    });
+    runtimeLog("info", "terminal_message_send", {
+        conversation_id: conversation.conversation_id,
+        agent: executor.kind,
+        terminal_target: terminalControl.target,
+        message: textSummary(message.body)
+    });
+    const deliveredConversation = markTakeoverBootstrapped({
+        conversation: nextConversation,
+        statePath,
+        logPath,
+        executor,
+        native: needsNativeTakeoverBootstrap,
+        fork: false
+    });
+    printJson({
+        conversation: deliveredConversation,
+        message,
+        delivered: true,
+        terminal_control: terminalControl,
+        executor,
+        budget: budgetAction(deliveredConversation)
+    });
+}
 function runNativeCodexResumeSend({ options, conversation, nextConversation, statePath, logPath, executor, executorEnv, message, payload, nativeTakeover, needsNativeTakeoverBootstrap }) {
     const codexPath = resolveExecutable("codex");
     const nativeSessionId = String(nativeTakeover["native_session_id"]);
@@ -3349,6 +3643,9 @@ function required(value, message) {
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+function stringValue(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
 function parseOptionalJson(text) {
     try {
         return JSON.parse(String(text));
@@ -3517,13 +3814,14 @@ function usage() {
   agent-knock-knock list [--store-dir <dir>] [--agent ${agentList}] [--status <status>] [--all]
   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>
   agent-knock-knock cancel --conversation <id> [--all-proxy <url>]
   agent-knock-knock recover --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
   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|fork [--create-conversation]
+  agent-knock-knock agent takeover --agent codex --session-id <id> --strategy safe_resume|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]