@scotthuang/agent-knock-knock 0.12.37 → 0.13.0

package/dist/src/terminal-list-cli-adapter.js

@@ -584,11 +584,13 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
         terminalState,
         nativeIdentityObservation,
         nativeAgentIdentity,
+        nativeIdentityAuthorityObservation: authorityNativeIdentityObservation,
+        codexOpenRootRolloutInventory,
         nativeProcessUuid,
         nativeProcessBirth
     });
     const terminalStatusSnapshot = effectiveTerminalState._terminal_status_snapshot
-        ? terminalBridgeStatusWithActivity(effectiveTerminalState._terminal_status_snapshot, effectiveTerminalState.activity_state, effectiveTerminalState.activity_reason)
+        ? terminalBridgeStatusWithProjection(effectiveTerminalState._terminal_status_snapshot, effectiveTerminalState)
         : undefined;
     const statusCardObservation = session.agent === "codex" &&
         typeof effectiveTerminalState.screen_excerpt === "string"
@@ -685,6 +687,21 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
             error: error instanceof Error ? error.message : String(error)
         });
     }
+    const commands = terminalListCommands({
+        agent: session.agent,
+        terminalControl,
+        terminalState: effectiveTerminalState,
+        lifecycleCapability,
+        nativeInspectionCapability,
+        nativeAgentIdentity: authorityNativeAgentIdentity,
+        nativeProcessUuid,
+        nativeProcessBirth,
+        codexLifecycleIncarnationAvailable,
+        automatedInputComposerReady,
+        hasOrphanedDispatch: orphanedDispatch !== undefined,
+        terminalHasBlockingTurn,
+        terminalHasInteraction: terminalStatusSnapshot?.interaction_state !== undefined
+    });
     const entry = {
         id: bridge.terminalConversationId(session),
         short_ref: sessionShortRef(bridge.terminalConversationId(session)),
@@ -724,6 +741,11 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
         approval_state: effectiveTerminalState.approval_state,
         activity_state: effectiveTerminalState.activity_state,
         activity_reason: effectiveTerminalState.activity_reason,
+        screen_state: effectiveTerminalState.screen_state,
+        screen_reason: effectiveTerminalState.screen_reason,
+        native_identity_state: effectiveTerminalState.native_identity_state,
+        durable_activity_state: effectiveTerminalState.durable_activity_state,
+        durable_activity_reason: effectiveTerminalState.durable_activity_reason,
         // Internal exact-observation evidence. The public projection strips this
         // object; raw terminal status reuses it so screen, approval, and activity
         // all describe the same capture.
@@ -768,20 +790,7 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
                 }
             }
             : {}),
-        commands: terminalListCommands({
-            agent: session.agent,
-            terminalControl,
-            terminalState: effectiveTerminalState,
-            lifecycleCapability,
-            nativeInspectionCapability,
-            nativeAgentIdentity: authorityNativeAgentIdentity,
-            nativeProcessUuid,
-            nativeProcessBirth,
-            codexLifecycleIncarnationAvailable,
-            automatedInputComposerReady,
-            hasOrphanedDispatch: orphanedDispatch !== undefined,
-            terminalHasBlockingTurn
-        })
+        commands
     };
     const renderedActions = renderAvailableListActions(entry);
     const terminalUserExplicitSendAuthority = decideTerminalUserExplicitSendAuthority({
@@ -817,17 +826,59 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
                 : {})
         }
         : undefined;
+    const foregroundIdentificationActions = terminalUserExplicitSendAuthority.eligible &&
+        commands.identify_foreground === true
+        ? {
+            identify_foreground: {
+                tool: "agent_knock_knock_identify_foreground",
+                arguments: {
+                    terminal_id: entry.id,
+                    expected_terminal_token: terminalUserExplicitSendAuthority.expectedTerminalToken
+                },
+                scope: "ephemeral_diagnostic_only",
+                grants_authority: false,
+                requires_user_intent: true
+            },
+            identify_and_send: {
+                tool: "agent_knock_knock_identify_and_send",
+                arguments: {
+                    terminal_id: entry.id,
+                    expected_terminal_token: terminalUserExplicitSendAuthority.expectedTerminalToken
+                },
+                missing_required: ["request"],
+                scope: "terminal_atomic_identify_and_send",
+                requires_user_intent: true
+            }
+        }
+        : {};
     const { commands: _commands, ...publicEntry } = entry;
     return {
         ...publicEntry,
         ...(terminalUserExplicitSendAction
             ? { _terminal_user_explicit_send_action: terminalUserExplicitSendAction }
             : {}),
-        available_actions: renderedActions
+        available_actions: {
+            ...renderedActions,
+            ...foregroundIdentificationActions
+        }
     };
 }
 function terminalListCommands(input) {
-    const { agent, terminalControl, terminalState, lifecycleCapability, nativeInspectionCapability, nativeAgentIdentity, nativeProcessUuid, nativeProcessBirth, codexLifecycleIncarnationAvailable, automatedInputComposerReady, hasOrphanedDispatch, terminalHasBlockingTurn } = input;
+    const { agent, terminalControl, terminalState, lifecycleCapability, nativeInspectionCapability, nativeAgentIdentity, nativeProcessUuid, nativeProcessBirth, codexLifecycleIncarnationAvailable, automatedInputComposerReady, hasOrphanedDispatch, terminalHasBlockingTurn, terminalHasInteraction } = input;
+    const foregroundIdentificationEligible = agent === "codex" &&
+        nativeInspectionCapability.status === "supported" &&
+        nativeInspectionCapability.statusInspection === true &&
+        terminalState.screen_state === "idle" &&
+        terminalState.native_identity_state !== "resolved" &&
+        terminalState.approval_state.scanned === true &&
+        terminalState.approval_state.blocked !== true &&
+        automatedInputComposerReady &&
+        codexLifecycleIncarnationAvailable &&
+        terminalControl.capabilities.includes("send_keys") &&
+        terminalControl.capabilities.includes("screen_status") &&
+        !terminalHasInteraction &&
+        !hasOrphanedDispatch &&
+        !terminalHasBlockingTurn;
     return {
         send: !terminalHasBlockingTurn,
         approve: terminalControl.capabilities.includes("terminal_approval") &&
@@ -854,31 +905,61 @@ function terminalListCommands(input) {
                     nativeAgentIdentity.processUuid)) &&
             !hasOrphanedDispatch &&
             !terminalHasBlockingTurn,
+        identify_foreground: foregroundIdentificationEligible,
+        identify_and_send: foregroundIdentificationEligible,
         watch: terminalControl.capabilities.includes("screen_status") ||
             Boolean(nativeAgentIdentity?.sessionId &&
                 (agent !== "codex" || nativeAgentIdentity.rollout))
     };
 }
 function effectiveTerminalListState(input) {
-    const { session, terminalState, nativeIdentityObservation, nativeAgentIdentity, nativeProcessUuid, nativeProcessBirth } = input;
-    if (session.agent !== "codex" ||
-        terminalState.activity_state === "working" ||
-        terminalState.activity_state === "awaiting_approval" ||
-        terminalState.approval_state.blocked === true) {
-        return terminalState;
+    const { session, terminalState, nativeIdentityObservation, nativeAgentIdentity, nativeIdentityAuthorityObservation, codexOpenRootRolloutInventory, nativeProcessUuid, nativeProcessBirth } = input;
+    const nativeIdentityState = terminalNativeIdentityState({
+        observation: nativeIdentityAuthorityObservation,
+        codexOpenRootRolloutInventory
+    });
+    if (session.agent !== "codex") {
+        return terminalListStateWithStatusAxes({
+            terminalState,
+            legacyState: terminalState,
+            nativeIdentityState,
+            durableActivityState: "unknown",
+            durableActivityReason: `durable activity evidence is unavailable for ${session.agent} terminals`
+        });
     }
+    const liveScreenStateWins = terminalState.activity_state === "working" ||
+        terminalState.activity_state === "awaiting_approval" ||
+        terminalState.approval_state.blocked === true;
     if (nativeIdentityObservation.status === "verified_absent") {
-        return terminalState;
+        return terminalListStateWithStatusAxes({
+            terminalState,
+            legacyState: terminalState,
+            nativeIdentityState,
+            durableActivityState: "unknown",
+            durableActivityReason: "durable Codex activity is unknown because no open native rollout was observed"
+        });
     }
     if (nativeIdentityObservation.status !== "resolved" ||
         !nativeAgentIdentity?.rollout ||
         !nativeAgentIdentity.sessionId ||
         !nativeProcessUuid ||
         !nativeProcessBirth) {
-        return terminalListStateWithUnavailableDurableActivity(terminalState, nativeIdentityObservation.status === "unavailable"
+        const reason = nativeIdentityObservation.status === "unavailable"
             ? nativeIdentityObservation.reason ??
                 "exact Codex identity observation failed"
-            : "exact Codex rollout/process identity is incomplete");
+            : nativeIdentityState === "ambiguous"
+                ? "the foreground Codex native identity is ambiguous"
+                : "exact Codex rollout/process identity is incomplete";
+        const legacyState = liveScreenStateWins
+            ? terminalState
+            : terminalListStateWithUnavailableDurableActivity(terminalState, reason);
+        return terminalListStateWithStatusAxes({
+            terminalState,
+            legacyState,
+            nativeIdentityState,
+            durableActivityState: "unknown",
+            durableActivityReason: `durable Codex activity evidence is unavailable: ${reason}`
+        });
     }
     const currentIdentity = {
         sessionId: nativeAgentIdentity.sessionId,
@@ -887,14 +968,31 @@ function effectiveTerminalListState(input) {
         rollout: nativeAgentIdentity.rollout
     };
     try {
-        if (!captureCodexHumanStartedActiveTaskAnchor({ currentIdentity })) {
-            return terminalState;
-        }
-        return {
-            ...terminalState,
-            activity_state: "working",
-            activity_reason: "Codex rollout contains an exact unfinished human-started task"
-        };
+        const activeTask = Boolean(captureCodexHumanStartedActiveTaskAnchor({ currentIdentity }));
+        const activeTaskReason = "Codex rollout contains an exact unfinished human-started task";
+        const durableActivityState = nativeIdentityState === "resolved"
+            ? activeTask ? "working" : "idle"
+            : "unknown";
+        const durableActivityReason = nativeIdentityState !== "resolved"
+            ? `durable Codex activity evidence is unavailable because the ` +
+                `foreground native identity is ${nativeIdentityState}`
+            : activeTask
+                ? activeTaskReason
+                : "exact Codex rollout contains no unfinished human-started task";
+        const legacyState = liveScreenStateWins || !activeTask
+            ? terminalState
+            : {
+                ...terminalState,
+                activity_state: "working",
+                activity_reason: activeTaskReason
+            };
+        return terminalListStateWithStatusAxes({
+            terminalState,
+            legacyState,
+            nativeIdentityState,
+            durableActivityState,
+            durableActivityReason
+        });
     }
     catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
@@ -903,8 +1001,40 @@ function effectiveTerminalListState(input) {
             pid: session.pid,
             reason
         });
-        return terminalListStateWithUnavailableDurableActivity(terminalState, reason);
+        const legacyState = liveScreenStateWins
+            ? terminalState
+            : terminalListStateWithUnavailableDurableActivity(terminalState, reason);
+        return terminalListStateWithStatusAxes({
+            terminalState,
+            legacyState,
+            nativeIdentityState,
+            durableActivityState: "unknown",
+            durableActivityReason: `durable Codex activity evidence is unavailable: ${reason}`
+        });
+    }
+}
+function terminalNativeIdentityState(input) {
+    if (input.observation.status === "resolved") {
+        return "resolved";
+    }
+    if (input.codexOpenRootRolloutInventory?.status === "unbound") {
+        return "ambiguous";
+    }
+    if (input.observation.status === "verified_absent" ||
+        input.codexOpenRootRolloutInventory?.status === "verified_absent") {
+        return "verified_absent";
     }
+    return "unavailable";
+}
+function terminalListStateWithStatusAxes(input) {
+    return {
+        ...input.legacyState,
+        screen_state: input.terminalState.screen_state,
+        screen_reason: input.terminalState.screen_reason,
+        native_identity_state: input.nativeIdentityState,
+        durable_activity_state: input.durableActivityState,
+        durable_activity_reason: input.durableActivityReason
+    };
 }
 function terminalListStateWithUnavailableDurableActivity(terminalState, reason) {
     return {
@@ -913,20 +1043,34 @@ function terminalListStateWithUnavailableDurableActivity(terminalState, reason)
         activity_reason: `durable Codex activity evidence is unavailable: ${reason}`
     };
 }
-function terminalBridgeStatusWithActivity(status, activityState, activityReason) {
+function terminalBridgeStatusWithProjection(status, projection) {
     const descriptors = Object.getOwnPropertyDescriptors(status);
     descriptors.activity_state = {
         configurable: true,
         enumerable: true,
-        value: activityState,
+        value: projection.activity_state,
         writable: true
     };
     descriptors.activity_reason = {
         configurable: true,
         enumerable: true,
-        value: activityReason,
+        value: projection.activity_reason,
         writable: true
     };
+    for (const [field, value] of Object.entries({
+        screen_state: projection.screen_state,
+        screen_reason: projection.screen_reason,
+        native_identity_state: projection.native_identity_state,
+        durable_activity_state: projection.durable_activity_state,
+        durable_activity_reason: projection.durable_activity_reason
+    })) {
+        descriptors[field] = {
+            configurable: true,
+            enumerable: true,
+            value,
+            writable: true
+        };
+    }
     return Object.create(Object.getPrototypeOf(status), descriptors);
 }
 async function observeTerminalNativeListIdentity(session, terminalControl, options, bridge) {
@@ -2584,7 +2728,9 @@ async function listStateForTerminal(agent, terminalControl, options, bridge = te
                 reason: "approval scan disabled"
             },
             activity_state: "unknown",
-            activity_reason: "terminal screen scan disabled"
+            activity_reason: "terminal screen scan disabled",
+            screen_state: "unknown",
+            screen_reason: "terminal screen scan disabled"
         };
     }
     try {
@@ -2599,6 +2745,8 @@ async function listStateForTerminal(agent, terminalControl, options, bridge = te
             },
             activity_state: status.activity_state,
             activity_reason: status.activity_reason,
+            screen_state: status.screen_state ?? status.activity_state,
+            screen_reason: status.screen_reason ?? status.activity_reason,
             capability_limitation: status.capability_limitation,
             _terminal_status_snapshot: status,
             // Internal projection evidence; terminalControlledListEntry selects all
@@ -2615,7 +2763,9 @@ async function listStateForTerminal(agent, terminalControl, options, bridge = te
                 error: error instanceof Error ? error.message : String(error)
             },
             activity_state: "unknown",
-            activity_reason: error instanceof Error ? error.message : String(error)
+            activity_reason: error instanceof Error ? error.message : String(error),
+            screen_state: "unknown",
+            screen_reason: error instanceof Error ? error.message : String(error)
         };
     }
 }