@scotthuang/agent-knock-knock 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.6.1 - 2026-07-30
+
+### Added
+
+- Return per-session `available_actions` and a versioned action contract from `AKK list`, including exact tool names, authoritative target arguments, fresh-status approval prerequisites, and recovery message IDs when currently available.
+
+### Fixed
+
+- Exclude unsupported and retired ACPX executor records from session discovery so historical Cursor or pre-tmux state cannot break valid Codex and Claude Code routing, while active legacy ownership still fences its pane against double dispatch.
+- Keep idle cleanup logging safe when it closes an unsupported legacy executor record.
+
 ## 0.6.0 - 2026-07-30
 
 ### Changed

package/README.md

@@ -197,6 +197,8 @@ The core command surface is intentionally small:
 
 Selectors fail closed: `only` works only with one actionable target, `latest` requires a unique newest target, and `codex` or `claude` must identify exactly one eligible pane. `AKK list` shows stable short references while JSON output retains the authoritative full IDs. Before every terminal operation, AKK revalidates the expected agent PID and tmux pane identity, then confirms that the process and pane working directories still match; every send also revalidates the idle prompt immediately before typing.
 
+For natural-language tool use, `agent_knock_knock_list` returns an `available_actions` object on rows in `delegated[]` and `terminal_controlled[]`; `tasks[]` remains a compatibility summary. Use only an action shown there, start with its prefilled authoritative arguments, and supply every `missing_required` field. `send` uses `selector`; status, approval, cancellation, renewal, callback retry, and close use `conversation_id`. For an ordinary send, add only `request`—`timeoutSeconds` is not a supported argument, and monitoring limits should be omitted unless the user explicitly asks to change them.
+
 Workspace is not a routing boundary. AKK can list, inspect, and control verified panes across projects; when more than one target matches, use a selector to choose one explicitly.
 
 If no eligible pane exists, AKK stops with setup guidance. If a send is ambiguous, run `/akk list` and retry with the returned `@short-ref`.

package/dist/src/cli.js

@@ -11,7 +11,7 @@ import { captureClaudeTranscriptAnchor, defaultClaudeHome, detectClaudeTranscrip
 import { CodexLocalSessionProvider } from "./codex-local-session-provider.js";
 import { CodexStoreAdapter } from "./codex-store-adapter.js";
 import { applyMessageToConversation, budgetAction, createConversation, createMessage, executorForConversation, extractStructuredMessage, parseMessageJson, resolveExecutor } from "./protocol.js";
-import { EXECUTOR_KINDS, executorDefinitionForKind } from "./executors.js";
+import { EXECUTOR_KINDS, executorDefinitionForKind, isExecutorKind } from "./executors.js";
 import { redactString, writeRuntimeLog } from "./runtime-log.js";
 import { formatTranscript, readNdjsonLog } from "./transcript.js";
 import { appendEvent, defaultStoreDir, ensureDir, listConversations, logPathForStatePath, loadConversationById, loadState, messageEvent, pathsForConversation, pathsForConversationDir, saveState, statePathForConversationId } from "./store.js";
@@ -1331,16 +1331,23 @@ async function runList(options) {
     const includeAll = Boolean(options.all);
     const agentFilter = options.agent ? resolveExecutor({ kind: options.agent }).kind : undefined;
     const statusFilter = options.status;
-    const storedConversations = listConversations(storeDir)
+    const allStoredConversations = listConversations(storeDir);
+    const storedConversations = allStoredConversations
+        .filter(isDiscoverableTmuxConversation)
         .filter((conversation) => includeAll || isActiveStatus(conversation.status))
         .filter((conversation) => matchesConfiguredWorkspace(options.workspace, conversation.workspace))
         .filter((conversation) => !agentFilter || executorForConversation(conversation).kind === agentFilter)
         .filter((conversation) => !statusFilter || conversation.status === statusFilter);
     const conversations = storedConversations.map((conversation) => summarizeConversation(conversation));
-    const delegated = storedConversations.map((conversation) => delegatedListEntry(summarizeConversation(conversation), { terminalBridge: terminalBridgeEnabled(conversation) }));
+    const delegated = storedConversations.map((conversation) => delegatedListEntry(summarizeConversation(conversation), {
+        terminalBridge: terminalBridgeEnabled(conversation),
+        approvalState: managedListApprovalState(conversation),
+        conversation
+    }));
     const terminalScan = await buildTerminalListGroup({ options, agentFilter, statusFilter });
-    const managedTerminalKeys = new Set(storedConversations
+    const managedTerminalKeys = new Set(allStoredConversations
         .filter((conversation) => isActiveStatus(conversation.status))
+        .filter((conversation) => matchesConfiguredWorkspace(options.workspace, conversation.workspace))
         .map((conversation) => terminalControlSelectorKey(terminalControlFromTakeover(isRecord(conversation.native_session_takeover)
         ? conversation.native_session_takeover
         : undefined)))
@@ -1355,6 +1362,7 @@ async function runList(options) {
     printJson({
         store_dir: storeDir,
         cleanup,
+        action_contracts: listActionContracts(),
         delegated,
         terminal_controlled: terminalControlled,
         terminal_scan: {
@@ -1454,12 +1462,13 @@ async function terminalControlDiagnostics(provider) {
         paneCount: (await provider.listPanes()).length
     };
 }
-function delegatedListEntry(task, { terminalBridge = false } = {}) {
-    return {
+function delegatedListEntry(task, { terminalBridge = false, approvalState, conversation } = {}) {
+    const entry = {
         ...task,
         id: task.conversation_id,
         short_ref: sessionShortRef(task.conversation_id),
         source: "akk_delegate",
+        ...(approvalState ? { approval_state: approvalState } : {}),
         commands: {
             send: canSendDelegated(task.status),
             cancel: isWaitingForAgent(task.status),
@@ -1468,6 +1477,10 @@ function delegatedListEntry(task, { terminalBridge = false } = {}) {
             approve: terminalBridge && isActiveStatus(task.status)
         }
     };
+    return {
+        ...entry,
+        available_actions: availableListActions(entry, { conversation })
+    };
 }
 async function terminalControlledListEntry(session, activeSessions, options, bridge = createTerminalAgentBridge(options)) {
     const terminalControl = session.terminalControl;
@@ -1481,7 +1494,7 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
         terminalTarget: terminalControl.target
     });
     const orphanedDispatch = orphanedTerminalDispatchForRecovery(terminalControl);
-    return {
+    const entry = {
         id: bridge.terminalConversationId(session),
         short_ref: sessionShortRef(bridge.terminalConversationId(session)),
         source: "terminal_control",
@@ -1520,6 +1533,10 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
             close: orphanedDispatch !== undefined
         }
     };
+    return {
+        ...entry,
+        available_actions: availableListActions(entry)
+    };
 }
 async function listStateForTerminal(agent, terminalControl, options, bridge = createTerminalAgentBridge(options), runtime) {
     if (options.noApprovalScan) {
@@ -1586,7 +1603,218 @@ function childPidsForRoot(root, processes) {
         .map((process) => process.pid);
 }
 function canSendDelegated(status) {
-    return !["failed", "closed", "cancelled"].includes(status);
+    return !["done", "failed", "closed", "cancelled"].includes(status);
+}
+function managedListApprovalState(conversation) {
+    if (!terminalBridgeEnabled(conversation) ||
+        !["waiting_for_agent", "waiting_for_openclaw"].includes(String(conversation.status))) {
+        return undefined;
+    }
+    const nativeTakeover = isRecord(conversation.native_session_takeover)
+        ? conversation.native_session_takeover
+        : undefined;
+    if (!terminalControlFromTakeover(nativeTakeover) ||
+        !stringValue(nativeTakeover?.terminal_bridge_message_id)) {
+        return undefined;
+    }
+    const approval = isRecord(nativeTakeover?.terminal_bridge_approval)
+        ? nativeTakeover.terminal_bridge_approval
+        : undefined;
+    const approvalState = isRecord(approval?.approval_state)
+        ? approval.approval_state
+        : undefined;
+    const fingerprint = stringValue(approval?.fingerprint);
+    const notifiedAt = stringValue(approval?.notified_at);
+    const notifiedAtMs = validTimestampMs(notifiedAt);
+    if (!approvalState ||
+        !fingerprint ||
+        notifiedAtMs === undefined ||
+        Date.now() - notifiedAtMs > CLAUDE_SCREEN_APPROVAL_TTL_MS) {
+        return undefined;
+    }
+    return {
+        ...approvalState,
+        fingerprint,
+        notified_at: notifiedAt
+    };
+}
+function listActionContracts() {
+    return {
+        version: 1,
+        instructions: [
+            "Use only actions present in delegated[].available_actions or terminal_controlled[].available_actions.",
+            "Start with the action's prefilled arguments, supply every missing_required field, and consult the top-level action's optional fields only when needed.",
+            "Authoritative full IDs are prefilled; short_ref is for display and human input.",
+            "Availability is a snapshot. AKK revalidates process, tmux pane, workspace, activity, approval, and recovery state before side effects."
+        ],
+        actions: {
+            send: {
+                tool: "agent_knock_knock_send",
+                target_argument: "selector",
+                required: ["request"],
+                optional: [
+                    "selector",
+                    "type",
+                    "idleTimeoutMinutes",
+                    "agentTimeoutMinutes",
+                    "agentHardTimeoutMinutes"
+                ],
+                unsupported: ["timeoutSeconds"],
+                ordinary_use: "Add request only. Omit timeout fields unless the user explicitly asks to change monitoring limits."
+            },
+            status: {
+                tool: "agent_knock_knock_status",
+                target_argument: "conversation_id",
+                required: ["conversation_id"],
+                optional: ["idleTimeoutMinutes", "trace"]
+            },
+            approve: {
+                tool: "agent_knock_knock_approve",
+                target_argument: "conversation_id",
+                required: ["conversation_id", "expected_approval_fingerprint"],
+                requires_explicit_user_confirmation: true,
+                requires_fresh_status: true
+            },
+            cancel: {
+                tool: "agent_knock_knock_cancel",
+                target_argument: "conversation_id",
+                required: ["conversation_id"],
+                optional: ["idleTimeoutMinutes"],
+                requires_user_intent: true
+            },
+            renew: {
+                tool: "agent_knock_knock_renew",
+                target_argument: "conversation_id",
+                required: ["conversation_id"],
+                optional: ["minutes"]
+            },
+            retry_callback: {
+                tool: "agent_knock_knock_retry_callback",
+                target_argument: "conversation_id",
+                required: ["conversation_id"]
+            },
+            close: {
+                tool: "agent_knock_knock_close",
+                target_argument: "conversation_id",
+                required: ["conversation_id"],
+                optional: ["reason", "expected_message_id"],
+                requires_explicit_user_confirmation: true
+            }
+        }
+    };
+}
+function availableListActions(entry, { conversation } = {}) {
+    const id = stringValue(entry.id ?? entry.conversation_id);
+    if (!id) {
+        return {};
+    }
+    const commands = isRecord(entry.commands) ? entry.commands : {};
+    const actions = {
+        status: {
+            tool: "agent_knock_knock_status",
+            arguments: { conversation_id: id }
+        }
+    };
+    const terminalControlled = entry.source === "terminal_control";
+    const managed = entry.source === "akk_delegate";
+    const approvalState = isRecord(entry.approval_state)
+        ? entry.approval_state
+        : {};
+    const nativeTakeover = isRecord(conversation?.native_session_takeover)
+        ? conversation.native_session_takeover
+        : undefined;
+    const managedApprovalPending = isRecord(nativeTakeover?.terminal_bridge_approval);
+    const terminalBridgeReady = managed &&
+        terminalBridgeEnabled(conversation) &&
+        terminalControlFromTakeover(nativeTakeover) !== undefined;
+    if (commands.send === true &&
+        ((terminalBridgeReady &&
+            ["waiting_for_openclaw", "idle"].includes(String(entry.status)) &&
+            !managedApprovalPending &&
+            approvalState.blocked !== true) ||
+            (terminalControlled &&
+                entry.activity_state === "idle" &&
+                approvalState.blocked !== true))) {
+        actions.send = {
+            tool: "agent_knock_knock_send",
+            arguments: { selector: id },
+            missing_required: ["request"]
+        };
+    }
+    const approvalFingerprint = stringValue(approvalState.fingerprint);
+    const managedApprovalEligible = terminalBridgeReady &&
+        entry.status === "waiting_for_openclaw" &&
+        (entry.agent !== "claude" ||
+            approvalState.decision_mode === "keys");
+    if (commands.approve === true &&
+        approvalState.approvable === true &&
+        approvalFingerprint &&
+        ((terminalControlled &&
+            entry.agent === "codex") ||
+            managedApprovalEligible)) {
+        actions.approve = {
+            tool: "agent_knock_knock_approve",
+            arguments: { conversation_id: id },
+            missing_required: ["expected_approval_fingerprint"],
+            before_call: {
+                tool: "agent_knock_knock_status",
+                arguments: { conversation_id: id },
+                use: "After explicit user confirmation, copy the latest terminal_status.approval_state.fingerprint into expected_approval_fingerprint."
+            },
+            requires_explicit_user_confirmation: true,
+            requires_fresh_status: true
+        };
+    }
+    const rawCancellable = terminalControlled &&
+        commands.cancel === true &&
+        (entry.activity_state === "working" ||
+            (approvalState.blocked === true &&
+                approvalState.approvable === true));
+    const managedCancellable = terminalBridgeReady &&
+        ["waiting_for_agent", "waiting_for_openclaw"].includes(String(entry.status)) &&
+        !(managedApprovalPending &&
+            approvalState.approvable !== true);
+    if (rawCancellable || managedCancellable) {
+        actions.cancel = {
+            tool: "agent_knock_knock_cancel",
+            arguments: { conversation_id: id },
+            requires_user_intent: true
+        };
+    }
+    if (terminalBridgeReady && entry.status === "stalled") {
+        actions.renew = {
+            tool: "agent_knock_knock_renew",
+            arguments: { conversation_id: id }
+        };
+    }
+    const callbackDelivery = isRecord(conversation?.callback_delivery)
+        ? conversation.callback_delivery
+        : undefined;
+    if (managed &&
+        isRecord(conversation) &&
+        isRetryableCallbackDelivery(conversation, callbackDelivery)) {
+        actions.retry_callback = {
+            tool: "agent_knock_knock_retry_callback",
+            arguments: { conversation_id: id }
+        };
+    }
+    if (commands.close === true) {
+        const orphanedDispatch = isRecord(entry.orphaned_terminal_dispatch)
+            ? entry.orphaned_terminal_dispatch
+            : undefined;
+        const expectedMessageId = stringValue(orphanedDispatch?.message_id);
+        actions.close = {
+            tool: "agent_knock_knock_close",
+            arguments: {
+                conversation_id: id,
+                ...(expectedMessageId
+                    ? { expected_message_id: expectedMessageId }
+                    : {})
+            },
+            requires_explicit_user_confirmation: true
+        };
+    }
+    return actions;
 }
 async function resolveConversationSelectorOption(commandName, options) {
     if (!SESSION_SELECTOR_COMMANDS.has(String(commandName ?? "")) ||
@@ -1617,7 +1845,13 @@ async function sessionSelectorCandidates(commandName, options) {
     const storedConversations = listConversations(storeDir);
     const workspaceConversations = storedConversations
         .filter((conversation) => matchesConfiguredWorkspace(options.workspace, conversation.workspace));
-    const managed = workspaceConversations.map((conversation) => delegatedListEntry(summarizeConversation(conversation), { terminalBridge: terminalBridgeEnabled(conversation) }));
+    const discoverableWorkspaceConversations = workspaceConversations
+        .filter(isDiscoverableTmuxConversation);
+    const managed = discoverableWorkspaceConversations.map((conversation) => delegatedListEntry(summarizeConversation(conversation), {
+        terminalBridge: terminalBridgeEnabled(conversation),
+        approvalState: managedListApprovalState(conversation),
+        conversation
+    }));
     const managedTerminalKeys = new Set(workspaceConversations
         .filter((conversation) => isActiveStatus(conversation.status))
         .map((conversation) => terminalControlSelectorKey(terminalControlFromTakeover(isRecord(conversation.native_session_takeover)
@@ -7370,6 +7604,34 @@ function summarizeConversation(conversation) {
         event_log_path: conversation.event_log_path
     };
 }
+function isDiscoverableTmuxConversation(conversation) {
+    if (!isRecord(conversation)) {
+        return false;
+    }
+    if (!isRecord(conversation.executor)) {
+        return false;
+    }
+    const kind = stringValue(conversation.executor.kind)?.toLowerCase();
+    return (kind !== undefined &&
+        isExecutorKind(kind) &&
+        conversation.executor.transport === "tmux");
+}
+function persistedExecutorLogFields(conversation) {
+    if (isDiscoverableTmuxConversation(conversation)) {
+        const executor = executorForConversation(conversation);
+        return {
+            agent: executor.kind,
+            executor_session: executor.session
+        };
+    }
+    const rawExecutor = isRecord(conversation?.executor)
+        ? conversation.executor
+        : {};
+    return {
+        agent: stringValue(rawExecutor.kind) ?? "unsupported",
+        executor_session: stringValue(rawExecutor.session)
+    };
+}
 function summarizeEvent(event) {
     return {
         ts: event.ts,
@@ -7986,10 +8248,10 @@ function cleanupIdleConversations(storeDir, options = {}, now = new Date()) {
                 idle_timeout_minutes: timeoutMinutes,
                 terminal_bridge: terminalBridge
             });
+            const executorLogFields = persistedExecutorLogFields(conversation);
             runtimeLog("info", "idle_conversation_closed", {
                 conversation_id: conversation.conversation_id,
-                agent: executorForConversation(conversation).kind,
-                executor_session: executorForConversation(conversation).session,
+                ...executorLogFields,
                 state_path: statePath,
                 event_log_path: logPath,
                 idle_since: conversation.idle_since,