Hmbown/CodeWhale · error

Windows list_windows does not support app_ref or window_id…

Error message

Windows list_windows does not support app_ref or window_id; omit them to list all windows

What it means

The Windows (win32) backend of the computer-use plugin's list_windows only enumerates ALL top-level windows; it cannot filter by app_ref or window_id. The implementation guards at entry and throws unsupportedSelector if either key is present, because Win32 window enumeration produces a flat list with no selector-based lookup path.

Solutions

  1. Call list_windows with no app_ref or window_id arguments to get all windows.
  2. Filter the returned windows client-side by title or owning process name to emulate the selector.
  3. If you need app-scoped state instead, use get_app_state with app_ref: { name: <exact window title> }.
  4. Use list_apps first to find the exact title/pid, then match against the full list_windows result.

Example fix

// before
await computerUse({ action: "list_windows", app_ref: { name: "Notepad" } });
// after
const all = await computerUse({ action: "list_windows" });
const windows = all.windows.filter(w => w.title === "Notepad");
Defensive patterns

Strategy: validation

Validate before calling

if (args && ("app_ref" in args || "window_id" in args)) delete args.app_ref, delete args.window_id; // win32: list all, filter client-side

Type guard

const selectorFree = (a) => a == null || !("app_ref" in a || "window_id" in a);

Try / catch

try { await listWindows(args) } catch (e) { if (String(e.message).includes("does not support")) { args = {}; /* retry unfiltered */ } else throw e; }

Prevention

When it happens

Trigger: Calling the computer-use tool with action list_windows on Windows while passing app_ref (e.g. {name|pid|bundle_id}) or window_id in the arguments.

Common situations: Porting automation scripts written against the macOS backend (which supports selectors) to Windows; an LLM agent emitting the same arguments it used on another platform; copying a call that previously targeted a specific app's windows.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/db10709010fd146d. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/plugins/computer-use/src/backends/win32.mjs:293

$arr = @([System.Windows.Forms.Screen]::AllScreens | ForEach-Object { [pscustomobject]@{ name = $_.DeviceName; primary = $_.Primary; x = $_.Bounds.X; y = $_.Bounds.Y; w = $_.Bounds.Width; h = $_.Bounds.Height } });
@{ displays = $arr } | ConvertTo-Json -Depth 4 -Compress;`, { timeoutMs: 15_000 });
      return d.displays.map((x, i) => ({ index: i + 1, name: x.name, points: { x: x.x, y: x.y, w: x.w, h: x.h }, pixels: { w: x.w, h: x.h }, scale: 1, main: !!x.primary }));
    },
    async switch_display({ index = 1 }) {
      const displays = await this.list_displays();
      if (!displays.some(d => d.index === index)) throw new ExecError("display index is out of range");
      activeDisplay = index;
      return { activeDisplay };
    },
    list_apps: async () => {
      const j = await psJson(`Add-Type -AssemblyName System.Windows.Forms;
$out = Get-Process | Where-Object { $_.MainWindowTitle } | ForEach-Object { [pscustomobject]@{ name = $_.ProcessName; pid2 = $_.Id; title = $_.MainWindowTitle } } | ConvertTo-Json -Compress;
if (-not $out) { $out = '[]' }
Write-Output ('{"apps": ' + $out + '}');`);
      return { apps: (Array.isArray(j.apps) ? j.apps : [j.apps]).map((a) => ({ name: a.name, pid: a.pid2, title: a.title })) };
    },
    list_windows: async (args = {}) => {
      if (Object.hasOwn(args, "app_ref") || Object.hasOwn(args, "window_id")) throw unsupportedSelector("Windows list_windows does not support app_ref or window_id; omit them to list all windows");
      const j = await psJson(`$ErrorActionPreference = 'Stop';
Add-Type -AssemblyName System.Windows.Forms;
Add-Type -TypeDefinition @'
using System;
using System.Text;
using System.Collections.Generic;
using System.Runtime.InteropServices;
public static class WinEnum {
  [DllImport("user32.dll")] static extern bool EnumWindows(EnumWindowsProc lpEnumFunc, IntPtr lParam);
  [DllImport("user32.dll")] static extern bool IsWindowVisible(IntPtr hWnd);
  [DllImport("user32.dll")] static extern int GetWindowText(IntPtr hWnd, StringBuilder text, int count);
  [DllImport("user32.dll")] static extern int GetWindowTextLength(IntPtr hWnd);
  [DllImport("user32.dll")] static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint pid);
  [DllImport("user32.dll")] static extern bool GetWindowRect(IntPtr hWnd, out RECT rect);
  [StructLayout(LayoutKind.Sequential)] public struct RECT { public int Left; public int Top; public int Right; public int Bottom; }
  delegate bool EnumWindowsProc(IntPtr hWnd, IntPtr lParam);
  public static List<string> List() {
    var result = new List<string>();

View on GitHub (pinned to 73e0f67d83)