@logictan/dsh-desktop-agent 0.1.0 → 0.1.2

package/README.md

@@ -48,8 +48,8 @@ to the `cua_driver_native__*` tools it publishes and has no driver of its own.
 
 `desktop_agent({ app, goal, windowId })` resolves one window, runs the
 observe/decide/act loop until `DONE`/`BLOCKED` or a cap is reached, and returns a
-structured trace. `app` accepts a bundle id, an application name, or a window
-title; omitting it uses the frontmost window.
+structured trace. `app` accepts an application name or a window title; omitting
+it uses the frontmost window.
 
 Only on-screen windows are eligible. A covered window cannot be captured or acted
 on, so the tool fails with the window named rather than screenshotting whatever

package/lib/index.js

@@ -151,7 +151,7 @@ export function apply(ctx, config) {
       'delivery — the plugin settings control that. This tool waits for the run to finish and returns a structured ' +
       'trace of every step.',
     parameters: {
-      app: { type: 'string', description: 'Application to drive: a bundle id, an app name, or a window title. Omit to use the frontmost window.' },
+      app: { type: 'string', description: 'Application to drive: an app name or a window title. Omit to use the frontmost window.' },
       goal: { type: 'string', description: 'What must be true when the task is finished.', required: true },
       windowId: { type: 'integer', description: 'Exact window id from a prior listing. Omit to resolve the window from the app argument.' },
     },
@@ -235,7 +235,12 @@ async function resolveTarget(input) {
 
   const value = await dispatch('cua_driver_native__list_windows', {}, signal);
   const payload = structured(value, 'list_windows');
-  const windows = Array.isArray(payload.windows) ? payload.windows : [];
+  // A payload that parses but carries no window array is a driver contract
+  // failure, not an empty desktop. Flattening it to [] would report the two as
+  // the same sentence, and the driver is a third-party boundary whose response
+  // shape this plugin does not control.
+  if (!Array.isArray(payload.windows)) throw new Error('desktop_agent: list_windows returned no window array.');
+  const windows = payload.windows;
   if (windows.length === 0) throw new Error('desktop_agent: the driver listed no windows.');
 
   if (args.windowId !== undefined) {
@@ -262,20 +267,41 @@ async function resolveTarget(input) {
   }
 
   const needle = args.app.toLowerCase();
-  const matches = onScreen.filter(
-    (window) =>
-      String(window.app_name ?? '').toLowerCase().includes(needle) ||
-      String(window.title ?? '').toLowerCase().includes(needle),
-  );
+  const matches = onScreen.filter((window) => matchesApp(window, needle));
   if (matches.length === 0) {
+    // An app that is running but has no window on screen is a different fact
+    // from an app that is not running, and only the second one suggests
+    // launching it. The windowId path already tells them apart.
+    if (windows.some((window) => matchesApp(window, needle))) {
+      throw new Error(
+        'desktop_agent: "' + args.app + '" is open, but no window of it is on screen, so it cannot be captured or acted on.',
+      );
+    }
     const names = [...new Set(onScreen.map((window) => window.app_name).filter(Boolean))];
     throw new Error(
-      'desktop_agent: no on-screen window matches "' + args.app + '". Open windows: ' + (names.join(', ') || '(none)') + '.',
+      'desktop_agent: no on-screen window matches "' + args.app + '". On-screen apps: ' + (names.join(', ') || '(none)') + '.',
     );
   }
   return targetOf(bestMatch(matches));
 }
 
+/**
+ * Whether a window answers to an app argument.
+ *
+ * The needle is matched against the application name and the window title,
+ * because both are things a caller can reasonably name.
+ *
+ * @param window - a window from the driver's list.
+ * @param needle - the app argument, lower-cased.
+ * @returns whether the window matches.
+ */
+function matchesApp(window, needle) {
+  return (
+    String(window.app_name ?? '').toLowerCase().includes(needle) ||
+    String(window.title ?? '').toLowerCase().includes(needle)
+  );
+}
+
 /**
  * Choose the window to drive from the candidates an app argument matched.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logictan/dsh-desktop-agent",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "DSH desktop agent: a native-vision decision loop that drives the host desktop through the Cua Driver tools. DSH 桌面 Agent 子插件。",
   "type": "module",
   "main": "lib/index.js",