@scotthuang/agent-knock-knock 0.2.20 → 0.2.22

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.2.22 - 2026-07-04
+
+### Added
+
+- Added `AKK describe` / `AKK summary` to summarize what an AKK-managed, native Codex, or terminal-controlled Codex session is about.
+- Added the `agent_knock_knock_describe` OpenClaw tool and `/akk describe <conversation-id>` command.
+- Reused Codex rollout history for exact session matches, added cwd-based fallback matching, and returned screen-only summaries with explicit low-confidence limitations when no history can be found.
+
+## 0.2.21 - 2026-07-03
+
+### Added
+
+- Added structured tmux Codex activity detection for terminal-controlled sessions, exposing `activity_state` and `activity_reason` in `AKK status` and `AKK list`.
+- Classified terminal-controlled Codex panes as `awaiting_approval`, `working`, `idle`, or `unknown` using conservative current-screen heuristics.
+- Added regression coverage for approval, stale approval scrollback, working, idle, unknown, and list activity-state output.
+
 ## 0.2.20 - 2026-07-02
 
 ### Fixed

package/README.md

@@ -118,6 +118,7 @@ AKK Claude: review the latest commit
 AKK Cursor: fix the flaky UI test
 akk list
 akk status <conversation-id>
+akk describe <conversation-id>
 akk send <conversation-id>: continue with the smaller implementation
 akk cancel <conversation-id>
 akk recover <conversation-id>
@@ -173,6 +174,7 @@ AKK list
 - `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.
 - `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.
 
 Takeover prompts:
 

package/dist/src/cli.js

@@ -92,6 +92,9 @@ async function runCommand(commandName, options) {
     else if (commandName === "status") {
         await runStatus(options);
     }
+    else if (commandName === "describe" || commandName === "summary") {
+        await runDescribe(options);
+    }
     else if (commandName === "send") {
         await runSend(options);
     }
@@ -669,6 +672,53 @@ function isPostApprovalActivityLine(line) {
     }
     return /^─\s*Worked for\b/u.test(trimmed);
 }
+function detectCodexActivityState(screen, approval = detectCodexApprovalPrompt(screen)) {
+    if (approval.approvable || isCodexApprovalPromptVisible(screen)) {
+        return {
+            state: "awaiting_approval",
+            reason: "current Codex approval prompt is visible"
+        };
+    }
+    const tailLines = screen.trimEnd().split(/\r?\n/).slice(-30);
+    const workingLine = tailLines.find((line) => isCodexWorkingLine(line));
+    if (workingLine) {
+        return {
+            state: "working",
+            reason: `Codex working marker detected: ${workingLine.trim()}`
+        };
+    }
+    const lastLine = tailLines
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .at(-1);
+    if (lastLine && isCodexIdlePromptLine(lastLine)) {
+        return {
+            state: "idle",
+            reason: `Codex input prompt detected: ${lastLine}`
+        };
+    }
+    return {
+        state: "unknown",
+        reason: "no current Codex working, idle, or approval marker was detected in the terminal screen"
+    };
+}
+function isCodexWorkingLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+        return false;
+    }
+    if (/^•\s+Working\b/u.test(trimmed)) {
+        return true;
+    }
+    if (/\besc to interrupt\b/u.test(trimmed) && (/\bWorking\b/u.test(trimmed) || /\b\/stop to close\b/u.test(trimmed))) {
+        return true;
+    }
+    return /\bbackground terminal running\b/u.test(trimmed);
+}
+function isCodexIdlePromptLine(line) {
+    const trimmed = line.trim();
+    return /^›(?:\s|$)/u.test(trimmed) && !/^›\s*1\./u.test(trimmed);
+}
 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);
@@ -1415,7 +1465,7 @@ async function terminalControlledListEntry(session, activeSessions, options) {
     if (!terminalControl) {
         throw new Error(`process ${session.pid} is not terminal-controlled`);
     }
-    const approvalState = await approvalStateForTerminal(terminalControl, options);
+    const terminalState = await listStateForTerminal(terminalControl, options);
     return {
         id: `terminal:${terminalControl.kind}:${terminalControl.target}:${session.pid}`,
         source: "terminal_control",
@@ -1431,23 +1481,29 @@ async function terminalControlledListEntry(session, activeSessions, options) {
         confidence: session.confidence,
         reason: session.reason,
         terminal_control: terminalControl,
-        approval_state: approvalState,
+        approval_state: terminalState.approval_state,
+        activity_state: terminalState.activity_state,
+        activity_reason: terminalState.activity_reason,
         commands: {
             send: true,
-            approve: approvalState.approvable === true,
+            approve: terminalState.approval_state.approvable === true,
             status: true,
             cancel: true,
             close: false
         }
     };
 }
-async function approvalStateForTerminal(terminalControl, options) {
+async function listStateForTerminal(terminalControl, options) {
     if (options.noApprovalScan) {
         return {
-            scanned: false,
-            blocked: false,
-            approvable: false,
-            reason: "approval scan disabled"
+            approval_state: {
+                scanned: false,
+                blocked: false,
+                approvable: false,
+                reason: "approval scan disabled"
+            },
+            activity_state: "unknown",
+            activity_reason: "terminal screen scan disabled"
         };
     }
     try {
@@ -1457,22 +1513,31 @@ async function approvalStateForTerminal(terminalControl, options) {
         });
         const approval = detectCodexApprovalPrompt(screen);
         const blocked = isCodexApprovalPromptVisible(screen);
+        const activity = detectCodexActivityState(screen, approval);
         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
+            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: blocked ? screenExcerpt(screen, 1000) : undefined
+            },
+            activity_state: activity.state,
+            activity_reason: activity.reason
         };
     }
     catch (error) {
         return {
-            scanned: false,
-            blocked: false,
-            approvable: false,
-            error: error instanceof Error ? error.message : String(error)
+            approval_state: {
+                scanned: false,
+                blocked: false,
+                approvable: false,
+                error: error instanceof Error ? error.message : String(error)
+            },
+            activity_state: "unknown",
+            activity_reason: error instanceof Error ? error.message : String(error)
         };
     }
 }
@@ -1539,6 +1604,21 @@ function parseTerminalConversationId(conversationId) {
         pid
     };
 }
+function parseNativeConversationId(conversationId) {
+    const prefix = "native:codex:";
+    if (!conversationId?.startsWith(prefix)) {
+        return undefined;
+    }
+    const pid = Number(conversationId.slice(prefix.length));
+    if (!Number.isInteger(pid)) {
+        throw new Error(`invalid native conversation id: ${conversationId}`);
+    }
+    return {
+        conversationId,
+        agent: "codex",
+        pid
+    };
+}
 async function runStatus(options) {
     cleanupIdleConversations(storeDirFromOptions(options), options);
     const terminalConversation = await resolveTerminalConversationFromOptions(options);
@@ -1587,6 +1667,55 @@ async function runStatus(options) {
         trace: Boolean(options.trace)
     });
 }
+async function runDescribe(options) {
+    cleanupIdleConversations(storeDirFromOptions(options), options);
+    const conversationId = required(options.conversation ?? options.conversationId, "--conversation is required");
+    const terminalConversation = await resolveTerminalConversationFromOptions(options);
+    if (terminalConversation) {
+        const terminalStatus = await terminalStatusForControl(terminalConversation.terminalControl, options);
+        const process = await activeCodexProcessForPid(options, parseTerminalConversationId(conversationId)?.pid);
+        printJson(await describeNativeCodexSession({
+            id: conversationId,
+            source: "terminal_control",
+            process,
+            options,
+            terminalControl: terminalConversation.terminalControl,
+            terminalStatus
+        }));
+        return;
+    }
+    const nativeConversation = parseNativeConversationId(conversationId);
+    if (nativeConversation) {
+        const process = await activeCodexProcessForPid(options, nativeConversation.pid);
+        printJson(await describeNativeCodexSession({
+            id: conversationId,
+            source: "native_active",
+            process,
+            options
+        }));
+        return;
+    }
+    const { conversation, statePath, logPath } = loadConversationFromOptions(options);
+    const events = readExistingEvents(logPath);
+    const terminalControl = terminalControlFromTakeover(isRecord(conversation.native_session_takeover) ? conversation.native_session_takeover : undefined);
+    const terminalStatus = terminalControl ? await terminalStatusForControl(terminalControl, options) : undefined;
+    printJson({
+        conversation_id: conversation.conversation_id,
+        source: "akk_managed",
+        confidence: "high",
+        about: managedConversationAbout(conversation, events, terminalStatus),
+        summary: summarizeConversation(conversation),
+        evidence: {
+            initial_request: conversation.user_request,
+            recent_messages: recentMessageEvidence(events),
+            trace: buildConversationTrace({ conversation, events, logPath }),
+            terminal_screen: terminalStatus?.screen
+        },
+        limitations: terminalStatus?.reachable === false ? ["terminal status unavailable"] : [],
+        state_path: statePath,
+        event_log_path: logPath
+    });
+}
 async function terminalStatusForControl(terminalControl, options) {
     try {
         const screen = await createTerminalControlProvider(options).capture(terminalControl.target, {
@@ -1595,10 +1724,13 @@ async function terminalStatusForControl(terminalControl, options) {
         });
         const approval = detectCodexApprovalPrompt(screen);
         const blocked = isCodexApprovalPromptVisible(screen);
+        const activity = detectCodexActivityState(screen, approval);
         return {
             provider: terminalControl.kind,
             target: terminalControl.target,
             reachable: true,
+            activity_state: activity.state,
+            activity_reason: activity.reason,
             approval_state: {
                 scanned: true,
                 blocked,
@@ -1618,6 +1750,8 @@ async function terminalStatusForControl(terminalControl, options) {
             provider: terminalControl.kind,
             target: terminalControl.target,
             reachable: false,
+            activity_state: "unknown",
+            activity_reason: error instanceof Error ? error.message : String(error),
             approval_state: {
                 scanned: false,
                 blocked: false,
@@ -3574,6 +3708,168 @@ function summarizeEvent(event) {
         body: typeof event.body === "string" ? event.body.slice(0, 500) : undefined
     };
 }
+async function activeCodexProcessForPid(options, pid) {
+    if (!Number.isInteger(pid)) {
+        return undefined;
+    }
+    const provider = createAgentSessionProvider("codex", options);
+    const activeSessions = await listActiveSessionsWithTerminalControl(provider, options);
+    return activeSessions.find((process) => process.pid === pid);
+}
+async function describeNativeCodexSession({ id, source, process, options, terminalControl, terminalStatus }) {
+    const provider = createAgentSessionProvider("codex", options);
+    const directSessionId = process?.sessionId;
+    if (directSessionId) {
+        const context = await provider.getForkContext({
+            sessionId: directSessionId,
+            maxMessages: Number(options.maxMessages ?? 16),
+            maxCommands: Number(options.maxCommands ?? 10),
+            maxTextLength: Number(options.maxTextLength ?? 1200)
+        });
+        if (context) {
+            return nativeDescriptionFromContext({
+                id,
+                source,
+                confidence: "high",
+                match: "session_id",
+                process,
+                context,
+                terminalControl,
+                terminalStatus,
+                limitations: []
+            });
+        }
+    }
+    const cwd = process?.cwd ?? terminalControl?.currentPath;
+    const sessions = (await provider.listHistoricalSessions())
+        .filter((session) => session.cwd === cwd)
+        .sort((left, right) => Number(right.updatedAtMs ?? 0) - Number(left.updatedAtMs ?? 0));
+    if (sessions.length > 0) {
+        const selected = sessions[0];
+        const context = await provider.getForkContext({
+            sessionId: selected.id,
+            maxMessages: Number(options.maxMessages ?? 16),
+            maxCommands: Number(options.maxCommands ?? 10),
+            maxTextLength: Number(options.maxTextLength ?? 1200)
+        });
+        if (context) {
+            return nativeDescriptionFromContext({
+                id,
+                source,
+                confidence: sessions.length === 1 ? "medium" : "low",
+                match: sessions.length === 1 ? "cwd" : "cwd_latest",
+                process,
+                context,
+                terminalControl,
+                terminalStatus,
+                limitations: sessions.length === 1
+                    ? ["Codex session inferred from matching cwd because the active process did not expose a session id."]
+                    : [`Codex session inferred from the most recent of ${sessions.length} sessions with the same cwd.`],
+                candidates: sessions.slice(0, 5).map((session) => ({
+                    session_id: session.id,
+                    cwd: session.cwd,
+                    title: session.title ?? session.preview ?? session.firstUserMessage,
+                    updated_at_ms: session.updatedAtMs,
+                    capability: session.capability
+                }))
+            });
+        }
+    }
+    return {
+        conversation_id: id,
+        source,
+        confidence: "screen_only",
+        match: "terminal_screen",
+        about: screenOnlyAbout({ process, terminalStatus }),
+        evidence: {
+            process,
+            terminal_control: terminalControl,
+            terminal_status: terminalStatus
+        },
+        limitations: [
+            "No exact Codex session id was available.",
+            cwd ? "No matching Codex rollout history was found for this cwd." : "No process cwd was available for Codex history matching.",
+            "Summary is limited to active process metadata and the visible terminal screen."
+        ]
+    };
+}
+function nativeDescriptionFromContext({ id, source, confidence, match, process, context, terminalControl, terminalStatus, limitations, candidates }) {
+    return {
+        conversation_id: id,
+        source,
+        confidence,
+        match,
+        about: rolloutAbout(context, terminalStatus),
+        codex_session: context.source,
+        evidence: {
+            process,
+            terminal_control: terminalControl,
+            terminal_status: terminalStatus,
+            initial_request: firstUserText(context),
+            title: context.source.title,
+            recent_messages: context.messages.slice(-8),
+            recent_commands: context.commands.slice(-8),
+            candidates
+        },
+        limitations
+    };
+}
+function managedConversationAbout(conversation, events, terminalStatus) {
+    const request = truncateText(String(conversation.user_request ?? "").trim(), 220);
+    const recent = recentMessageEvidence(events).at(-1)?.body;
+    const parts = [
+        request ? `Initial request: ${request}` : undefined,
+        recent ? `Latest visible message: ${truncateText(recent, 180)}` : undefined,
+        terminalStatus?.activity_state ? `Current terminal state: ${terminalStatus.activity_state}.` : undefined
+    ].filter(Boolean);
+    return parts.length > 0 ? parts.join(" ") : "No durable task content is available for this AKK-managed session.";
+}
+function rolloutAbout(context, terminalStatus) {
+    const title = truncateText(String(context.source.title ?? "").trim(), 180);
+    const firstUser = firstUserText(context);
+    const latestAssistant = [...context.messages].reverse().find((message) => message.role === "assistant")?.text;
+    const latestCommand = context.commands.at(-1)?.command;
+    const parts = [
+        firstUser ? `Initial request: ${truncateText(firstUser, 220)}` : title ? `Codex title: ${title}` : undefined,
+        latestAssistant ? `Latest visible progress: ${truncateText(latestAssistant, 180)}` : undefined,
+        latestCommand ? `Recent command: ${truncateText(latestCommand, 140)}` : undefined,
+        terminalStatus?.activity_state ? `Current terminal state: ${terminalStatus.activity_state}.` : undefined
+    ].filter(Boolean);
+    return parts.length > 0 ? parts.join(" ") : "Codex history was found, but it did not include enough visible message content to summarize the session.";
+}
+function screenOnlyAbout({ process, terminalStatus }) {
+    const activity = terminalStatus?.activity_reason ?? terminalStatus?.activity_state;
+    const excerpt = terminalStatus?.screen?.excerpt;
+    const parts = [
+        process?.cwd ? `This Codex process is running in ${process.cwd}.` : undefined,
+        activity ? `Terminal activity: ${truncateText(String(activity), 180)}` : undefined,
+        excerpt ? `Visible screen: ${truncateText(String(excerpt), 220)}` : undefined
+    ].filter(Boolean);
+    return parts.length > 0 ? parts.join(" ") : "Only active process metadata is available; no Codex conversation history or terminal screen content could be read.";
+}
+function firstUserText(context) {
+    return context.messages.find((message) => message.role === "user")?.text ?? context.source.title;
+}
+function recentMessageEvidence(events) {
+    return events
+        .filter((event) => event.event === "message" && typeof event.body === "string")
+        .slice(-8)
+        .map((event) => ({
+        ts: event.ts,
+        from: event.from,
+        to: event.to,
+        type: event.type,
+        round: event.round,
+        body: truncateText(event.body, 800)
+    }));
+}
+function truncateText(value, maxLength) {
+    const text = String(value ?? "").replace(/\s+/g, " ").trim();
+    if (text.length <= maxLength) {
+        return text;
+    }
+    return `${text.slice(0, Math.max(0, maxLength - 3))}...`;
+}
 function buildConversationTrace({ conversation, events, logPath }) {
     const outputPath = traceOutputPath({ conversation, events, logPath });
     const output = outputPath && fs.existsSync(outputPath)
@@ -4581,6 +4877,7 @@ function usage() {
   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] [--managed-only] [--no-approval-scan] [--terminal-debug]
   agent-knock-knock status --conversation <id> [--store-dir <dir>] [--trace]
+  agent-knock-knock describe --conversation <id> [--store-dir <dir>]
   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>]