@scotthuang/agent-knock-knock 0.2.21 → 0.2.23

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.2.23 - 2026-07-04
+
+### Fixed
+
+- Declared `agent_knock_knock_describe` in the OpenClaw plugin contract and metadata so OpenClaw exposes the new describe tool.
+- Updated the installed AKK skill routing rules to use `agent_knock_knock_describe` for session-content summary requests instead of falling back to direct terminal inspection.
+
+## 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

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);
     }
@@ -1601,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);
@@ -1649,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, {
@@ -3641,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)
@@ -4648,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>]