@vascend/talos 0.1.0 → 0.1.2

package/dist/vendor/computer-use/computer-observe.js

@@ -1,315 +1,315 @@
-'use strict';
-
-// Layer di OSSERVAZIONE di Computer Use: funzioni pure che normalizzano,
-// filtrano, compattano e confrontano quello che il desktop restituisce. Nessuna
-// I/O, nessuna politica: si testa senza toccare Windows.
-//
-// Il criterio guida e' il costo di contesto. Il tree UI Automation di una app
-// reale produce centinaia di nodi: consegnarli tutti, con tutti i campi vuoti,
-// bruciava il turno prima di agire. Qui si filtra per intento e si emette solo
-// cio' che serve a decidere il passo successivo.
-
-const crypto = require('crypto');
-
-const INTERACTIVE_TYPES = Object.freeze(['Edit', 'Button', 'CheckBox', 'RadioButton', 'ComboBox',
-  'ListItem', 'MenuItem', 'TabItem', 'TreeItem', 'Hyperlink', 'Slider', 'Spinner', 'SplitButton',
-  'Document', 'Menu', 'List', 'Tree', 'Tab']);
-
-function integer(value, min, max, fallback = 0) {
-  const number = Math.trunc(Number(value));
-  return Number.isFinite(number) ? Math.max(min, Math.min(max, number)) : fallback;
-}
-
-function cleanBounds(value) {
-  const bounds = value && typeof value === 'object' ? value : {};
-  const x = Number(bounds.x); const y = Number(bounds.y);
-  const width = Number(bounds.width); const height = Number(bounds.height);
-  if (![x, y, width, height].every(Number.isFinite) || width < 1 || height < 1) return null;
-  return { x: Math.round(x), y: Math.round(y), width: Math.round(width), height: Math.round(height) };
-}
-
-function cleanWindow(value) {
-  const bounds = cleanBounds(value && value.bounds);
-  const windowId = String(value && value.windowId || '');
-  if (!bounds || !/^\d+$/.test(windowId)) return null;
-  return {
-    windowId,
-    processId: integer(value.processId, 0, 2147483647),
-    process: String(value.process || '').slice(0, 120),
-    title: String(value.title || '').slice(0, 300),
-    bounds,
-    visible: !(value && value.visible === false),
-    minimized: !!(value && value.minimized === true),
-  };
-}
-
-function cleanProcess(value) {
-  const processId = integer(value && value.processId, 0, 2147483647);
-  const process = String(value && value.process || '').trim().slice(0, 120);
-  if (!processId || !process) return null;
-  const windowId = /^\d+$/.test(String(value && value.windowId || ''))
-    ? String(value.windowId) : '';
-  return {
-    processId,
-    process,
-    title: String(value && value.title || '').slice(0, 300),
-    windowId,
-    hasWindow: value && typeof value.hasWindow === 'boolean' ? value.hasWindow : !!windowId,
-    bounds: cleanBounds(value && value.bounds),
-    visible: !(value && value.visible === false),
-    minimized: !!(value && value.minimized === true),
-    responding: !(value && value.responding === false),
-    // Campo strettamente host-side: serve per app.getFileIcon e viene rimosso
-    // da ogni evento/risposta pubblica prima di lasciare il modulo dei tool.
-    _executablePath: String(value && (value._executablePath || value.executablePath) || '').slice(0, 1024),
-  };
-}
-
-function cleanElement(value, index, scope = '') {
-  const bounds = cleanBounds(value && value.bounds);
-  const row = {
-    name: String(value && value.name || '').slice(0, 180),
-    automationId: String(value && value.automationId || '').slice(0, 120),
-    type: String(value && value.type || 'Control').slice(0, 80),
-    className: String(value && value.className || '').slice(0, 100),
-    processId: integer(value && value.processId, 0, 2147483647),
-    enabled: value && value.enabled !== false,
-    focusable: value && value.focusable === true,
-    isPassword: value && value.isPassword === true,
-    value: String(value && value.value || '').slice(0, 500),
-    toggle: String(value && value.toggle || '').slice(0, 40),
-    selected: typeof (value && value.selected) === 'boolean' ? value.selected : null,
-    expanded: String(value && value.expanded || '').slice(0, 40),
-    actions: Array.isArray(value && value.actions)
-      ? value.actions.map((item) => String(item || '').slice(0, 20)).filter(Boolean).slice(0, 6)
-      : [],
-    bounds,
-  };
-  if (!bounds && !row.automationId && !row.name) return null;
-  const identity = [String(scope || ''), row.processId, row.automationId,
-    row.type, row.className, row.name, index].join('|');
-  row.targetId = 'ui-' + crypto.createHash('sha256').update(identity).digest('hex').slice(0, 10);
-  return row;
-}
-
-// Selettore consegnato al layer nativo: identifica il controllo nel tree VIVO,
-// non una coordinata congelata.
-function selectorFor(element) {
-  const bounds = element && element.bounds ? element.bounds : null;
-  return {
-    automationId: String(element && element.automationId || ''),
-    name: String(element && element.name || ''),
-    type: String(element && element.type || ''),
-    className: String(element && element.className || ''),
-    centerX: bounds ? Math.round(bounds.x + bounds.width / 2) : 0,
-    centerY: bounds ? Math.round(bounds.y + bounds.height / 2) : 0,
-  };
-}
-
-function pointerFor(element) {
-  const bounds = element && element.bounds ? cleanBounds(element.bounds) : null;
-  if (!bounds) return null;
-  return { x: Math.round(bounds.x + bounds.width / 2), y: Math.round(bounds.y + bounds.height / 2) };
-}
-
-function normalizeQueryText(value) {
-  return String(value || '')
-    .normalize('NFKD').replace(/[\u0300-\u036f]/g, '')
-    .toLocaleLowerCase().replace(/\.exe\b/g, '').replace(/[^a-z0-9]+/g, ' ').trim();
-}
-
-function targetSearchScore(query, fields) {
-  const needle = normalizeQueryText(query);
-  if (!needle) return 1;
-  const tokens = needle.split(/\s+/).filter(Boolean);
-  let best = 0;
-  for (const field of fields.flatMap((value) => Array.isArray(value) ? value : [value])) {
-    const haystack = normalizeQueryText(field);
-    if (!haystack) continue;
-    if (haystack === needle) best = Math.max(best, 1000);
-    else if (haystack.startsWith(needle)) best = Math.max(best, 700);
-    else if (haystack.includes(needle)) best = Math.max(best, 500);
-    if (tokens.length && tokens.every((token) => haystack.includes(token))) {
-      best = Math.max(best, 300 + tokens.length * 20);
-    }
-  }
-  return best;
-}
-
-function searchedTargets(rows, query, limit, fields) {
-  return (Array.isArray(rows) ? rows : [])
-    .map((row, index) => ({ row, index, score: targetSearchScore(query, fields(row)) }))
-    .filter((entry) => entry.score > 0)
-    .sort((a, b) => b.score - a.score || a.index - b.index)
-    .slice(0, limit)
-    .map((entry) => entry.row);
-}
-
-// Selezione dei controlli per intento: query testuale, tipi richiesti, solo
-// interattivi. Restituisce anche quanti ne sono stati esclusi, perche' un
-// troncamento silenzioso e' peggio di un elenco corto e dichiarato.
-function filterElements(rows, options = {}) {
-  const all = Array.isArray(rows) ? rows.filter(Boolean) : [];
-  const query = String(options.query || '').trim();
-  const types = (Array.isArray(options.types) ? options.types : [])
-    .map((item) => String(item || '').trim().toLocaleLowerCase()).filter(Boolean);
-  const interactiveOnly = options.interactiveOnly === true;
-  const limit = integer(options.limit, 1, 320, 60);
-  const typed = types.length
-    ? all.filter((row) => types.includes(String(row.type || '').toLocaleLowerCase()))
-    : all;
-  const scoped = interactiveOnly
-    ? typed.filter((row) => INTERACTIVE_TYPES.includes(row.type)
-      || (Array.isArray(row.actions) && row.actions.length > 0))
-    : typed;
-  const matched = query
-    ? searchedTargets(scoped, query, scoped.length, (row) => [row.name, row.value, row.automationId, row.type])
-    : scoped;
-  return {
-    rows: matched.slice(0, limit),
-    total: all.length,
-    matched: matched.length,
-    truncated: Math.max(0, matched.length - limit),
-  };
-}
-
-// Vista compatta per il modello: fuori i campi vuoti, fuori gli identificativi
-// interni (automationId, className, processId) che non servono a decidere.
-// Il target_id resta l'unico riferimento stabile con cui agire.
-function compactElement(row) {
-  const compact = { targetId: row.targetId, type: row.type };
-  if (row.name) compact.name = row.name;
-  if (row.value) compact.value = row.value;
-  if (row.toggle) compact.toggle = row.toggle;
-  if (row.selected === true) compact.selected = true;
-  if (row.expanded) compact.expanded = row.expanded;
-  if (row.enabled === false) compact.disabled = true;
-  if (row.isPassword) compact.password = true;
-  if (Array.isArray(row.actions) && row.actions.length) compact.can = row.actions;
-  if (row.bounds) compact.bounds = [row.bounds.x, row.bounds.y, row.bounds.width, row.bounds.height];
-  return compact;
-}
-
-function similarity(expected, current) {
-  if (!expected || !current) return -1;
-  if (expected.processId && current.processId && expected.processId !== current.processId) return -1;
-  if (expected.automationId && expected.automationId !== current.automationId) return -1;
-  if (!expected.automationId && expected.name && expected.name !== current.name) return -1;
-  let score = 0;
-  if (expected.automationId && expected.automationId === current.automationId) score += 8;
-  if (expected.name && expected.name === current.name) score += 5;
-  if (expected.type === current.type) score += 3;
-  if (expected.className && expected.className === current.className) score += 2;
-  if (!expected.automationId && !expected.name && expected.bounds && current.bounds) {
-    const dx = Math.abs((expected.bounds.x + expected.bounds.width / 2) - (current.bounds.x + current.bounds.width / 2));
-    const dy = Math.abs((expected.bounds.y + expected.bounds.height / 2) - (current.bounds.y + current.bounds.height / 2));
-    if (dx + dy <= 48) score += 4;
-  }
-  return score;
-}
-
-function elementSignature(row) {
-  return [row.automationId, row.name, row.type, row.className].join('|');
-}
-
-// Delta fra due letture del tree: e' la verifica che il modello chiederebbe
-// comunque dopo ogni azione, ma costa una riga invece di un intero inventario.
-function diffElements(before, after, limit = 12) {
-  const previous = new Map((Array.isArray(before) ? before : []).map((row) => [elementSignature(row), row]));
-  const current = new Map((Array.isArray(after) ? after : []).map((row) => [elementSignature(row), row]));
-  const changes = [];
-  for (const [signature, row] of current) {
-    const old = previous.get(signature);
-    if (!old) {
-      changes.push({ change: 'appeared', type: row.type, ...(row.name ? { name: row.name } : {}),
-        ...(row.value ? { value: row.value } : {}) });
-      continue;
-    }
-    const fields = {};
-    if (old.value !== row.value) fields.value = row.value;
-    if (old.toggle !== row.toggle) fields.toggle = row.toggle;
-    if (old.selected !== row.selected && typeof row.selected === 'boolean') fields.selected = row.selected;
-    if (old.expanded !== row.expanded) fields.expanded = row.expanded;
-    if (old.enabled !== row.enabled) fields.enabled = row.enabled;
-    if (Object.keys(fields).length) {
-      changes.push({ change: 'updated', type: row.type, ...(row.name ? { name: row.name } : {}), ...fields });
-    }
-  }
-  for (const [signature, row] of previous) {
-    if (current.has(signature)) continue;
-    changes.push({ change: 'disappeared', type: row.type, ...(row.name ? { name: row.name } : {}) });
-  }
-  const ranked = changes.sort((a, b) => {
-    const weight = (change) => change === 'updated' ? 0 : change === 'appeared' ? 1 : 2;
-    return weight(a.change) - weight(b.change);
-  });
-  return { changes: ranked.slice(0, limit), changeCount: ranked.length };
-}
-
-function describeChanges(delta) {
-  const count = Number(delta && delta.changeCount) || 0;
-  if (!count) return 'nessun cambiamento rilevato nella finestra';
-  const first = delta.changes[0];
-  const label = first.change === 'appeared' ? 'e comparso' : first.change === 'disappeared' ? 'e scomparso' : 'e cambiato';
-  const subject = `${first.name || first.type}`.slice(0, 60);
-  return count === 1 ? `${subject} ${label}` : `${subject} ${label}, ${count - 1} altri cambiamenti`;
-}
-
-// Envelope unico: ogni tool dice com'e' andata (status), in una riga (summary) e
-// che cosa ha senso fare adesso (nextActions). Un errore senza il passo
-// successivo costringe il modello a indovinare.
-function ok(summary, data = {}, nextActions = []) {
-  return {
-    ok: true,
-    status: 'success',
-    summary: String(summary || '').slice(0, 240),
-    ...data,
-    ...(nextActions.length ? { nextActions: nextActions.slice(0, 4) } : {}),
-  };
-}
-
-function warn(summary, data = {}, nextActions = []) {
-  return { ...ok(summary, data, nextActions), status: 'warning' };
-}
-
-function fail(code, error, nextActions = [], data = {}) {
-  return {
-    ok: false,
-    status: 'error',
-    code: String(code || 'ERROR'),
-    error: String(error || 'Operazione non riuscita.').slice(0, 400),
-    ...data,
-    ...(nextActions.length ? { nextActions: nextActions.slice(0, 4) } : {}),
-  };
-}
-
-// Scorciatoie del menu Start: e' l'elenco che rende possibile "apri Spotify"
-// anche quando l'app non e' in esecuzione. Riceve nomi di file, non processi.
-function startMenuMatches(entries, query, limit = 6) {
-  const rows = (Array.isArray(entries) ? entries : []).filter((entry) => entry && entry.name && entry.path);
-  return searchedTargets(rows, query, integer(limit, 1, 20, 6), (row) => [row.name]);
-}
-
-module.exports = {
-  INTERACTIVE_TYPES,
-  integer,
-  cleanBounds,
-  cleanWindow,
-  cleanProcess,
-  cleanElement,
-  selectorFor,
-  pointerFor,
-  normalizeQueryText,
-  targetSearchScore,
-  searchedTargets,
-  filterElements,
-  compactElement,
-  similarity,
-  elementSignature,
-  diffElements,
-  describeChanges,
-  startMenuMatches,
-  ok,
-  warn,
-  fail,
-};
+'use strict';
+
+// Layer di OSSERVAZIONE di Computer Use: funzioni pure che normalizzano,
+// filtrano, compattano e confrontano quello che il desktop restituisce. Nessuna
+// I/O, nessuna politica: si testa senza toccare Windows.
+//
+// Il criterio guida e' il costo di contesto. Il tree UI Automation di una app
+// reale produce centinaia di nodi: consegnarli tutti, con tutti i campi vuoti,
+// bruciava il turno prima di agire. Qui si filtra per intento e si emette solo
+// cio' che serve a decidere il passo successivo.
+
+const crypto = require('crypto');
+
+const INTERACTIVE_TYPES = Object.freeze(['Edit', 'Button', 'CheckBox', 'RadioButton', 'ComboBox',
+  'ListItem', 'MenuItem', 'TabItem', 'TreeItem', 'Hyperlink', 'Slider', 'Spinner', 'SplitButton',
+  'Document', 'Menu', 'List', 'Tree', 'Tab']);
+
+function integer(value, min, max, fallback = 0) {
+  const number = Math.trunc(Number(value));
+  return Number.isFinite(number) ? Math.max(min, Math.min(max, number)) : fallback;
+}
+
+function cleanBounds(value) {
+  const bounds = value && typeof value === 'object' ? value : {};
+  const x = Number(bounds.x); const y = Number(bounds.y);
+  const width = Number(bounds.width); const height = Number(bounds.height);
+  if (![x, y, width, height].every(Number.isFinite) || width < 1 || height < 1) return null;
+  return { x: Math.round(x), y: Math.round(y), width: Math.round(width), height: Math.round(height) };
+}
+
+function cleanWindow(value) {
+  const bounds = cleanBounds(value && value.bounds);
+  const windowId = String(value && value.windowId || '');
+  if (!bounds || !/^\d+$/.test(windowId)) return null;
+  return {
+    windowId,
+    processId: integer(value.processId, 0, 2147483647),
+    process: String(value.process || '').slice(0, 120),
+    title: String(value.title || '').slice(0, 300),
+    bounds,
+    visible: !(value && value.visible === false),
+    minimized: !!(value && value.minimized === true),
+  };
+}
+
+function cleanProcess(value) {
+  const processId = integer(value && value.processId, 0, 2147483647);
+  const process = String(value && value.process || '').trim().slice(0, 120);
+  if (!processId || !process) return null;
+  const windowId = /^\d+$/.test(String(value && value.windowId || ''))
+    ? String(value.windowId) : '';
+  return {
+    processId,
+    process,
+    title: String(value && value.title || '').slice(0, 300),
+    windowId,
+    hasWindow: value && typeof value.hasWindow === 'boolean' ? value.hasWindow : !!windowId,
+    bounds: cleanBounds(value && value.bounds),
+    visible: !(value && value.visible === false),
+    minimized: !!(value && value.minimized === true),
+    responding: !(value && value.responding === false),
+    // Campo strettamente host-side: serve per app.getFileIcon e viene rimosso
+    // da ogni evento/risposta pubblica prima di lasciare il modulo dei tool.
+    _executablePath: String(value && (value._executablePath || value.executablePath) || '').slice(0, 1024),
+  };
+}
+
+function cleanElement(value, index, scope = '') {
+  const bounds = cleanBounds(value && value.bounds);
+  const row = {
+    name: String(value && value.name || '').slice(0, 180),
+    automationId: String(value && value.automationId || '').slice(0, 120),
+    type: String(value && value.type || 'Control').slice(0, 80),
+    className: String(value && value.className || '').slice(0, 100),
+    processId: integer(value && value.processId, 0, 2147483647),
+    enabled: value && value.enabled !== false,
+    focusable: value && value.focusable === true,
+    isPassword: value && value.isPassword === true,
+    value: String(value && value.value || '').slice(0, 500),
+    toggle: String(value && value.toggle || '').slice(0, 40),
+    selected: typeof (value && value.selected) === 'boolean' ? value.selected : null,
+    expanded: String(value && value.expanded || '').slice(0, 40),
+    actions: Array.isArray(value && value.actions)
+      ? value.actions.map((item) => String(item || '').slice(0, 20)).filter(Boolean).slice(0, 6)
+      : [],
+    bounds,
+  };
+  if (!bounds && !row.automationId && !row.name) return null;
+  const identity = [String(scope || ''), row.processId, row.automationId,
+    row.type, row.className, row.name, index].join('|');
+  row.targetId = 'ui-' + crypto.createHash('sha256').update(identity).digest('hex').slice(0, 10);
+  return row;
+}
+
+// Selettore consegnato al layer nativo: identifica il controllo nel tree VIVO,
+// non una coordinata congelata.
+function selectorFor(element) {
+  const bounds = element && element.bounds ? element.bounds : null;
+  return {
+    automationId: String(element && element.automationId || ''),
+    name: String(element && element.name || ''),
+    type: String(element && element.type || ''),
+    className: String(element && element.className || ''),
+    centerX: bounds ? Math.round(bounds.x + bounds.width / 2) : 0,
+    centerY: bounds ? Math.round(bounds.y + bounds.height / 2) : 0,
+  };
+}
+
+function pointerFor(element) {
+  const bounds = element && element.bounds ? cleanBounds(element.bounds) : null;
+  if (!bounds) return null;
+  return { x: Math.round(bounds.x + bounds.width / 2), y: Math.round(bounds.y + bounds.height / 2) };
+}
+
+function normalizeQueryText(value) {
+  return String(value || '')
+    .normalize('NFKD').replace(/[\u0300-\u036f]/g, '')
+    .toLocaleLowerCase().replace(/\.exe\b/g, '').replace(/[^a-z0-9]+/g, ' ').trim();
+}
+
+function targetSearchScore(query, fields) {
+  const needle = normalizeQueryText(query);
+  if (!needle) return 1;
+  const tokens = needle.split(/\s+/).filter(Boolean);
+  let best = 0;
+  for (const field of fields.flatMap((value) => Array.isArray(value) ? value : [value])) {
+    const haystack = normalizeQueryText(field);
+    if (!haystack) continue;
+    if (haystack === needle) best = Math.max(best, 1000);
+    else if (haystack.startsWith(needle)) best = Math.max(best, 700);
+    else if (haystack.includes(needle)) best = Math.max(best, 500);
+    if (tokens.length && tokens.every((token) => haystack.includes(token))) {
+      best = Math.max(best, 300 + tokens.length * 20);
+    }
+  }
+  return best;
+}
+
+function searchedTargets(rows, query, limit, fields) {
+  return (Array.isArray(rows) ? rows : [])
+    .map((row, index) => ({ row, index, score: targetSearchScore(query, fields(row)) }))
+    .filter((entry) => entry.score > 0)
+    .sort((a, b) => b.score - a.score || a.index - b.index)
+    .slice(0, limit)
+    .map((entry) => entry.row);
+}
+
+// Selezione dei controlli per intento: query testuale, tipi richiesti, solo
+// interattivi. Restituisce anche quanti ne sono stati esclusi, perche' un
+// troncamento silenzioso e' peggio di un elenco corto e dichiarato.
+function filterElements(rows, options = {}) {
+  const all = Array.isArray(rows) ? rows.filter(Boolean) : [];
+  const query = String(options.query || '').trim();
+  const types = (Array.isArray(options.types) ? options.types : [])
+    .map((item) => String(item || '').trim().toLocaleLowerCase()).filter(Boolean);
+  const interactiveOnly = options.interactiveOnly === true;
+  const limit = integer(options.limit, 1, 320, 60);
+  const typed = types.length
+    ? all.filter((row) => types.includes(String(row.type || '').toLocaleLowerCase()))
+    : all;
+  const scoped = interactiveOnly
+    ? typed.filter((row) => INTERACTIVE_TYPES.includes(row.type)
+      || (Array.isArray(row.actions) && row.actions.length > 0))
+    : typed;
+  const matched = query
+    ? searchedTargets(scoped, query, scoped.length, (row) => [row.name, row.value, row.automationId, row.type])
+    : scoped;
+  return {
+    rows: matched.slice(0, limit),
+    total: all.length,
+    matched: matched.length,
+    truncated: Math.max(0, matched.length - limit),
+  };
+}
+
+// Vista compatta per il modello: fuori i campi vuoti, fuori gli identificativi
+// interni (automationId, className, processId) che non servono a decidere.
+// Il target_id resta l'unico riferimento stabile con cui agire.
+function compactElement(row) {
+  const compact = { targetId: row.targetId, type: row.type };
+  if (row.name) compact.name = row.name;
+  if (row.value) compact.value = row.value;
+  if (row.toggle) compact.toggle = row.toggle;
+  if (row.selected === true) compact.selected = true;
+  if (row.expanded) compact.expanded = row.expanded;
+  if (row.enabled === false) compact.disabled = true;
+  if (row.isPassword) compact.password = true;
+  if (Array.isArray(row.actions) && row.actions.length) compact.can = row.actions;
+  if (row.bounds) compact.bounds = [row.bounds.x, row.bounds.y, row.bounds.width, row.bounds.height];
+  return compact;
+}
+
+function similarity(expected, current) {
+  if (!expected || !current) return -1;
+  if (expected.processId && current.processId && expected.processId !== current.processId) return -1;
+  if (expected.automationId && expected.automationId !== current.automationId) return -1;
+  if (!expected.automationId && expected.name && expected.name !== current.name) return -1;
+  let score = 0;
+  if (expected.automationId && expected.automationId === current.automationId) score += 8;
+  if (expected.name && expected.name === current.name) score += 5;
+  if (expected.type === current.type) score += 3;
+  if (expected.className && expected.className === current.className) score += 2;
+  if (!expected.automationId && !expected.name && expected.bounds && current.bounds) {
+    const dx = Math.abs((expected.bounds.x + expected.bounds.width / 2) - (current.bounds.x + current.bounds.width / 2));
+    const dy = Math.abs((expected.bounds.y + expected.bounds.height / 2) - (current.bounds.y + current.bounds.height / 2));
+    if (dx + dy <= 48) score += 4;
+  }
+  return score;
+}
+
+function elementSignature(row) {
+  return [row.automationId, row.name, row.type, row.className].join('|');
+}
+
+// Delta fra due letture del tree: e' la verifica che il modello chiederebbe
+// comunque dopo ogni azione, ma costa una riga invece di un intero inventario.
+function diffElements(before, after, limit = 12) {
+  const previous = new Map((Array.isArray(before) ? before : []).map((row) => [elementSignature(row), row]));
+  const current = new Map((Array.isArray(after) ? after : []).map((row) => [elementSignature(row), row]));
+  const changes = [];
+  for (const [signature, row] of current) {
+    const old = previous.get(signature);
+    if (!old) {
+      changes.push({ change: 'appeared', type: row.type, ...(row.name ? { name: row.name } : {}),
+        ...(row.value ? { value: row.value } : {}) });
+      continue;
+    }
+    const fields = {};
+    if (old.value !== row.value) fields.value = row.value;
+    if (old.toggle !== row.toggle) fields.toggle = row.toggle;
+    if (old.selected !== row.selected && typeof row.selected === 'boolean') fields.selected = row.selected;
+    if (old.expanded !== row.expanded) fields.expanded = row.expanded;
+    if (old.enabled !== row.enabled) fields.enabled = row.enabled;
+    if (Object.keys(fields).length) {
+      changes.push({ change: 'updated', type: row.type, ...(row.name ? { name: row.name } : {}), ...fields });
+    }
+  }
+  for (const [signature, row] of previous) {
+    if (current.has(signature)) continue;
+    changes.push({ change: 'disappeared', type: row.type, ...(row.name ? { name: row.name } : {}) });
+  }
+  const ranked = changes.sort((a, b) => {
+    const weight = (change) => change === 'updated' ? 0 : change === 'appeared' ? 1 : 2;
+    return weight(a.change) - weight(b.change);
+  });
+  return { changes: ranked.slice(0, limit), changeCount: ranked.length };
+}
+
+function describeChanges(delta) {
+  const count = Number(delta && delta.changeCount) || 0;
+  if (!count) return 'nessun cambiamento rilevato nella finestra';
+  const first = delta.changes[0];
+  const label = first.change === 'appeared' ? 'e comparso' : first.change === 'disappeared' ? 'e scomparso' : 'e cambiato';
+  const subject = `${first.name || first.type}`.slice(0, 60);
+  return count === 1 ? `${subject} ${label}` : `${subject} ${label}, ${count - 1} altri cambiamenti`;
+}
+
+// Envelope unico: ogni tool dice com'e' andata (status), in una riga (summary) e
+// che cosa ha senso fare adesso (nextActions). Un errore senza il passo
+// successivo costringe il modello a indovinare.
+function ok(summary, data = {}, nextActions = []) {
+  return {
+    ok: true,
+    status: 'success',
+    summary: String(summary || '').slice(0, 240),
+    ...data,
+    ...(nextActions.length ? { nextActions: nextActions.slice(0, 4) } : {}),
+  };
+}
+
+function warn(summary, data = {}, nextActions = []) {
+  return { ...ok(summary, data, nextActions), status: 'warning' };
+}
+
+function fail(code, error, nextActions = [], data = {}) {
+  return {
+    ok: false,
+    status: 'error',
+    code: String(code || 'ERROR'),
+    error: String(error || 'Operazione non riuscita.').slice(0, 400),
+    ...data,
+    ...(nextActions.length ? { nextActions: nextActions.slice(0, 4) } : {}),
+  };
+}
+
+// Scorciatoie del menu Start: e' l'elenco che rende possibile "apri Spotify"
+// anche quando l'app non e' in esecuzione. Riceve nomi di file, non processi.
+function startMenuMatches(entries, query, limit = 6) {
+  const rows = (Array.isArray(entries) ? entries : []).filter((entry) => entry && entry.name && entry.path);
+  return searchedTargets(rows, query, integer(limit, 1, 20, 6), (row) => [row.name]);
+}
+
+module.exports = {
+  INTERACTIVE_TYPES,
+  integer,
+  cleanBounds,
+  cleanWindow,
+  cleanProcess,
+  cleanElement,
+  selectorFor,
+  pointerFor,
+  normalizeQueryText,
+  targetSearchScore,
+  searchedTargets,
+  filterElements,
+  compactElement,
+  similarity,
+  elementSignature,
+  diffElements,
+  describeChanges,
+  startMenuMatches,
+  ok,
+  warn,
+  fail,
+};