@hoilab/ada-cli 0.84.21 → 0.85.0

package/dist/core/computer/motor/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../../src/core/computer/motor/state.ts"],"names":[],"mappings":"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","sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\nimport type { CdpPageSnapshot } from \"./cdp.ts\";\nimport type { ImageMode } from \"./contract.ts\";\nimport type { WindowNote } from \"./note.ts\";\nimport {\n\ttype LookResponse,\n\ttype Outline,\n\trestoreOutline,\n\ttype SerializedOutline,\n\tserializeOutline,\n} from \"./outline.ts\";\nimport { StateStore, type StoredState } from \"./runtime.ts\";\n\ninterface StateTargetSnapshot {\n\tpid: number;\n\twindowId: number;\n\twindowRef?: string;\n}\n\nexport interface CurrentTarget {\n\tappName: string;\n\tbundleId?: string;\n\tpid: number;\n\twindowTitle: string;\n\twindowId: number;\n\twindowRef?: string;\n\tnativeWindowRef?: string;\n}\n\nexport interface CurrentCapture {\n\tstateId: string;\n\twidth: number;\n\theight: number;\n\tscaleFactor: number;\n\ttimestamp: number;\n}\n\nexport interface OperationState {\n\tcurrentTarget?: CurrentTarget;\n\tcurrentCapture?: CurrentCapture;\n\tcurrentStateTarget?: StateTargetSnapshot;\n\tcurrentImageMode?: ImageMode;\n\tcurrentLook?: LookResponse;\n\tcurrentOutline?: Outline;\n\tcurrentNote?: WindowNote;\n\tresourceKey?: string;\n\tepoch?: number;\n\tlastSearchOcrEscalatedLookId?: string;\n\tbrowserSnapshot?: CdpPageSnapshot;\n\tcontextId?: string;\n}\n\ninterface DesktopObservation {\n\tkind: \"desktop\";\n\ttarget: CurrentTarget;\n\tcapture: CurrentCapture;\n\tlook: Omit<LookResponse, \"parsedOutline\" | \"outline\">;\n\toutline: SerializedOutline;\n\tnote?: WindowNote;\n\timageMode?: ImageMode;\n}\n\ninterface BrowserObservation {\n\tkind: \"browser\";\n\tsnapshot: CdpPageSnapshot;\n\toutline: SerializedOutline;\n}\n\nexport type UiObservation = DesktopObservation | BrowserObservation;\n\nexport class SavedStates {\n\treadonly store = new StateStore<UiObservation>(128);\n\treadonly operations = new AsyncLocalStorage<OperationState>();\n\n\tcurrent(): OperationState {\n\t\tconst state = this.operations.getStore();\n\t\tif (!state) throw new Error(\"Computer-use operation state is unavailable.\");\n\t\treturn state;\n\t}\n\n\tget(stateId: string): StoredState<UiObservation> | undefined {\n\t\treturn this.store.get(stateId);\n\t}\n\n\tset(record: StoredState<UiObservation>): void {\n\t\tthis.store.set(record);\n\t}\n\n\tclear(): void {\n\t\tthis.store.clear();\n\t}\n\n\thydrate(record: StoredState<UiObservation> | undefined): OperationState {\n\t\tif (!record) return {};\n\t\tif (record.value.kind === \"browser\") {\n\t\t\tconst outline = restoreOutline(record.value.outline);\n\t\t\treturn {\n\t\t\t\tcurrentCapture: {\n\t\t\t\t\tstateId: record.stateId,\n\t\t\t\t\twidth: 0,\n\t\t\t\t\theight: 0,\n\t\t\t\t\tscaleFactor: 1,\n\t\t\t\t\ttimestamp: record.value.snapshot.capturedAt,\n\t\t\t\t},\n\t\t\t\tcurrentLook: {\n\t\t\t\t\tlookId: record.value.snapshot.snapshotId,\n\t\t\t\t\tcapturedAt: record.value.snapshot.capturedAt / 1000,\n\t\t\t\t\twindow: {\n\t\t\t\t\t\twindowId: 0,\n\t\t\t\t\t\tframePoints: { x: 0, y: 0, w: 1, h: 1 },\n\t\t\t\t\t\tscaleFactor: 1,\n\t\t\t\t\t\tisModal: false,\n\t\t\t\t\t\trole: \"document\",\n\t\t\t\t\t\tsubrole: \"\",\n\t\t\t\t\t},\n\t\t\t\t\toutline: outline.root,\n\t\t\t\t\ttimings: {},\n\t\t\t\t\tparsedOutline: outline,\n\t\t\t\t},\n\t\t\t\tcurrentOutline: outline,\n\t\t\t\tresourceKey: record.resourceKey,\n\t\t\t\tepoch: record.epoch,\n\t\t\t\tbrowserSnapshot: record.value.snapshot,\n\t\t\t\tcontextId: record.value.snapshot.contextId,\n\t\t\t};\n\t\t}\n\t\tconst outline = restoreOutline(record.value.outline);\n\t\treturn {\n\t\t\tcurrentTarget: { ...record.value.target },\n\t\t\tcurrentCapture: { ...record.value.capture },\n\t\t\tcurrentStateTarget: {\n\t\t\t\tpid: record.value.target.pid,\n\t\t\t\twindowId: record.value.target.windowId,\n\t\t\t\twindowRef: record.value.target.windowRef,\n\t\t\t},\n\t\t\tcurrentImageMode: record.value.imageMode,\n\t\t\tcurrentLook: { ...record.value.look, outline: outline.root, parsedOutline: outline },\n\t\t\tcurrentOutline: outline,\n\t\t\tcurrentNote: record.value.note ? structuredClone(record.value.note) : undefined,\n\t\t\tresourceKey: record.resourceKey,\n\t\t\tepoch: record.epoch,\n\t\t};\n\t}\n\n\tsaveDesktop(state: OperationState, resourceKey: string, epoch: number): void {\n\t\tif (!state.currentTarget || !state.currentCapture || !state.currentLook || !state.currentOutline) return;\n\t\tthis.store.set({\n\t\t\tstateId: state.currentCapture.stateId,\n\t\t\tresourceKey,\n\t\t\tepoch,\n\t\t\tvalue: {\n\t\t\t\tkind: \"desktop\",\n\t\t\t\ttarget: { ...state.currentTarget },\n\t\t\t\tcapture: { ...state.currentCapture },\n\t\t\t\tlook: {\n\t\t\t\t\tlookId: state.currentLook.lookId,\n\t\t\t\t\tcapturedAt: state.currentLook.capturedAt,\n\t\t\t\t\twindow: structuredClone(state.currentLook.window),\n\t\t\t\t\timage: state.currentLook.image ? { ...state.currentLook.image } : undefined,\n\t\t\t\t\ttimings: { ...state.currentLook.timings },\n\t\t\t\t\treadText: state.currentLook.readText ? { ...state.currentLook.readText } : undefined,\n\t\t\t\t},\n\t\t\t\toutline: serializeOutline(state.currentOutline),\n\t\t\t\tnote: state.currentNote ? structuredClone(state.currentNote) : undefined,\n\t\t\t\timageMode: state.currentImageMode,\n\t\t\t},\n\t\t});\n\t}\n}\n"]}

package/dist/core/computer/motor/view.d.ts

@@ -0,0 +1,6 @@
+import { type Outline, type OutlineChange, type OutlineDiff } from "./outline.ts";
+/** Preserve public refs only when native or structural identity is unambiguous. */
+export declare function stabilizeRefs(base: Outline | undefined, next: Outline): Outline;
+export declare function changesBetween(base: Outline, next: Outline): OutlineDiff;
+export declare function renderChanges(changes: OutlineChange[]): string;
+//# sourceMappingURL=view.d.ts.map

package/dist/core/computer/motor/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../../../src/core/computer/motor/view.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,WAAW,EAIhB,MAAM,cAAc,CAAC;AA0CtB,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CA6B/E;AAwCD,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,WAAW,CA0CxE;AAiBD,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,MAAM,CAoB9D","sourcesContent":["import {\n\ttype Outline,\n\ttype OutlineChange,\n\ttype OutlineDiff,\n\ttype OutlineNode,\n\ttype SerializedOutlineNode,\n\tserializeOutlineNode,\n} from \"./outline.ts\";\n\nfunction numericRef(ref: string): number {\n\tconst match = /^@e(\\d+)$/.exec(ref);\n\treturn match ? Number(match[1]) : 0;\n}\n\nfunction rebuildIndexes(outline: Outline): void {\n\toutline.nodes = [];\n\toutline.refToWireRef = new Map();\n\toutline.wireRefToRef = new Map();\n\tconst queue = [outline.root];\n\twhile (queue.length > 0) {\n\t\tconst node = queue.shift()!;\n\t\toutline.nodes.push(node);\n\t\tif (node.wireRef) {\n\t\t\toutline.refToWireRef.set(node.ref, node.wireRef);\n\t\t\toutline.wireRefToRef.set(node.wireRef, node.ref);\n\t\t}\n\t\tqueue.push(...node.children);\n\t}\n}\n\nfunction structuralToken(node: OutlineNode): string {\n\treturn [node.role, node.subrole, node.identifier, node.title, node.description]\n\t\t.map((value) => value.trim().toLowerCase())\n\t\t.join(\"|\");\n}\n\nfunction structuralKey(node: OutlineNode): string {\n\tconst parts: string[] = [];\n\tlet current: OutlineNode | undefined = node;\n\twhile (current) {\n\t\tconst token = structuralToken(current);\n\t\tconst siblings = current.parent?.children ?? [current];\n\t\tconst peers = siblings.filter((candidate) => structuralToken(candidate) === token);\n\t\tparts.unshift(`${token}#${Math.max(0, peers.indexOf(current))}`);\n\t\tcurrent = current.parent;\n\t}\n\treturn parts.join(\">\");\n}\n\n/** Preserve public refs only when native or structural identity is unambiguous. */\nexport function stabilizeRefs(base: Outline | undefined, next: Outline): Outline {\n\tif (!base) return next;\n\tconst reserved = new Set<string>();\n\tconst assigned = new Set<OutlineNode>();\n\tconst byWireRef = new Map(base.nodes.filter((node) => node.wireRef).map((node) => [node.wireRef!, node.ref]));\n\tconst structuralGroups = new Map<string, OutlineNode[]>();\n\tfor (const node of base.nodes) {\n\t\tconst key = structuralKey(node);\n\t\tstructuralGroups.set(key, [...(structuralGroups.get(key) ?? []), node]);\n\t}\n\tlet nextIndex = Math.max(0, ...base.nodes.map((node) => numericRef(node.ref))) + 1;\n\tfor (const node of next.nodes) {\n\t\tconst wireStable = node.wireRef ? byWireRef.get(node.wireRef) : undefined;\n\t\tconst structuralMatches = structuralGroups.get(structuralKey(node)) ?? [];\n\t\tconst stable = wireStable ?? (structuralMatches.length === 1 ? structuralMatches[0].ref : undefined);\n\t\tif (stable && !reserved.has(stable)) {\n\t\t\tnode.ref = stable;\n\t\t\treserved.add(stable);\n\t\t\tassigned.add(node);\n\t\t}\n\t}\n\tfor (const node of next.nodes) {\n\t\tif (assigned.has(node)) continue;\n\t\twhile (reserved.has(`@e${nextIndex}`)) nextIndex += 1;\n\t\tnode.ref = `@e${nextIndex++}`;\n\t\treserved.add(node.ref);\n\t}\n\trebuildIndexes(next);\n\treturn next;\n}\n\nfunction comparable(node: OutlineNode): Omit<SerializedOutlineNode, \"children\"> {\n\tconst { children: _children, ...fields } = serializeOutlineNode(node);\n\treturn {\n\t\t...fields,\n\t\trect: fields.rect\n\t\t\t? {\n\t\t\t\t\tx: Math.round(fields.rect.x),\n\t\t\t\t\ty: Math.round(fields.rect.y),\n\t\t\t\t\tw: Math.round(fields.rect.w),\n\t\t\t\t\th: Math.round(fields.rect.h),\n\t\t\t\t}\n\t\t\t: undefined,\n\t\ttext: fields.text.map((item) => ({ string: item.string, confidence: Math.round(item.confidence * 100) / 100 })),\n\t};\n}\n\nfunction changedFields(base: OutlineNode, next: OutlineNode): Partial<Omit<SerializedOutlineNode, \"children\">> {\n\tconst before = comparable(base);\n\tconst after = comparable(next);\n\tconst fields: Partial<Omit<SerializedOutlineNode, \"children\">> = {};\n\tfor (const key of Object.keys(after) as Array<keyof typeof after>) {\n\t\tif (key === \"ref\" || key === \"wireRef\") continue;\n\t\tif (JSON.stringify(before[key]) !== JSON.stringify(after[key]))\n\t\t\t(fields as Record<string, unknown>)[key] = after[key];\n\t}\n\treturn fields;\n}\n\nfunction refPath(node: OutlineNode): string[] {\n\tconst refs: string[] = [];\n\tlet current: OutlineNode | undefined = node;\n\twhile (current) {\n\t\trefs.unshift(current.ref);\n\t\tcurrent = current.parent;\n\t}\n\treturn refs;\n}\n\nexport function changesBetween(base: Outline, next: Outline): OutlineDiff {\n\tif (base.root.role !== next.root.role || base.root.subrole !== next.root.subrole) {\n\t\treturn {\n\t\t\tchanges: [],\n\t\t\tchangedNodeCount: next.nodes.length,\n\t\t\tfullNodeCount: next.nodes.length,\n\t\t\tuseFullView: true,\n\t\t\treason: \"root_replaced\",\n\t\t};\n\t}\n\tconst before = new Map(base.nodes.map((node) => [node.ref, node]));\n\tconst after = new Map(next.nodes.map((node) => [node.ref, node]));\n\tconst changes: OutlineChange[] = [];\n\tfor (const node of next.nodes) {\n\t\tconst previous = before.get(node.ref);\n\t\tif (!previous)\n\t\t\tchanges.push({\n\t\t\t\ttype: \"added\",\n\t\t\t\tref: node.ref,\n\t\t\t\tparent: node.parent?.ref,\n\t\t\t\tnode: { ...serializeOutlineNode(node), children: [] },\n\t\t\t});\n\t\telse {\n\t\t\tconst fields = changedFields(previous, node);\n\t\t\tif (Object.keys(fields).length > 0)\n\t\t\t\tchanges.push({ type: \"updated\", ref: node.ref, path: refPath(node), fields });\n\t\t}\n\t}\n\tfor (const node of base.nodes)\n\t\tif (!after.has(node.ref)) changes.push({ type: \"removed\", ref: node.ref, parent: node.parent?.ref });\n\tconst identityConfidence =\n\t\tnext.nodes.length === 0 ? 1 : next.nodes.filter((node) => before.has(node.ref)).length / next.nodes.length;\n\tconst changeRatio = changes.length / Math.max(1, Math.max(base.nodes.length, next.nodes.length));\n\tconst identityLow = next.nodes.length > 8 && identityConfidence < 0.4;\n\tconst overBudget = changes.length > 100 || (changes.length > 20 && changeRatio > 0.65);\n\treturn {\n\t\tchanges,\n\t\tchangedNodeCount: changes.length,\n\t\tfullNodeCount: next.nodes.length,\n\t\tuseFullView: identityLow || overBudget,\n\t\treason: identityLow ? \"identity_confidence_low\" : overBudget ? \"change_budget_exceeded\" : undefined,\n\t};\n}\n\nfunction label(node: SerializedOutlineNode): string {\n\treturn (\n\t\tnode.title ||\n\t\tnode.description ||\n\t\tnode.value ||\n\t\tnode.identifier ||\n\t\tnode.text\n\t\t\t.map((item) => item.string)\n\t\t\t.join(\" \")\n\t\t\t.trim() ||\n\t\tnode.role ||\n\t\t\"node\"\n\t);\n}\n\nexport function renderChanges(changes: OutlineChange[]): string {\n\treturn changes\n\t\t.map((change) => {\n\t\t\tif (change.type === \"added\")\n\t\t\t\treturn `+ ${change.ref}${change.parent ? ` under ${change.parent}` : \"\"} ${JSON.stringify(label(change.node))}`;\n\t\t\tif (change.type === \"removed\") return `- ${change.ref}${change.parent ? ` from ${change.parent}` : \"\"}`;\n\t\t\tconst fields = Object.entries(change.fields)\n\t\t\t\t.filter(([key]) => ![\"rect\", \"text\", \"actions\"].includes(key))\n\t\t\t\t.slice(0, 6)\n\t\t\t\t.map(([key, value]) => `${key}=${JSON.stringify(value)}`)\n\t\t\t\t.join(\", \");\n\t\t\tconst supplemental = [\n\t\t\t\tchange.fields.text ? `text=${JSON.stringify(change.fields.text.map((item) => item.string))}` : undefined,\n\t\t\t\tchange.fields.actions ? `actions=${JSON.stringify(change.fields.actions)}` : undefined,\n\t\t\t]\n\t\t\t\t.filter(Boolean)\n\t\t\t\t.join(\", \");\n\t\t\treturn `~ ${change.ref} (${change.path.join(\" > \")}) ${[fields, supplemental].filter(Boolean).join(\", \") || \"changed\"}`;\n\t\t})\n\t\t.join(\"\\n\");\n}\n"]}

package/dist/core/computer/motor/view.js

@@ -0,0 +1,185 @@
+import { serializeOutlineNode, } from "./outline.js";
+function numericRef(ref) {
+    const match = /^@e(\d+)$/.exec(ref);
+    return match ? Number(match[1]) : 0;
+}
+function rebuildIndexes(outline) {
+    outline.nodes = [];
+    outline.refToWireRef = new Map();
+    outline.wireRefToRef = new Map();
+    const queue = [outline.root];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        outline.nodes.push(node);
+        if (node.wireRef) {
+            outline.refToWireRef.set(node.ref, node.wireRef);
+            outline.wireRefToRef.set(node.wireRef, node.ref);
+        }
+        queue.push(...node.children);
+    }
+}
+function structuralToken(node) {
+    return [node.role, node.subrole, node.identifier, node.title, node.description]
+        .map((value) => value.trim().toLowerCase())
+        .join("|");
+}
+function structuralKey(node) {
+    const parts = [];
+    let current = node;
+    while (current) {
+        const token = structuralToken(current);
+        const siblings = current.parent?.children ?? [current];
+        const peers = siblings.filter((candidate) => structuralToken(candidate) === token);
+        parts.unshift(`${token}#${Math.max(0, peers.indexOf(current))}`);
+        current = current.parent;
+    }
+    return parts.join(">");
+}
+/** Preserve public refs only when native or structural identity is unambiguous. */
+export function stabilizeRefs(base, next) {
+    if (!base)
+        return next;
+    const reserved = new Set();
+    const assigned = new Set();
+    const byWireRef = new Map(base.nodes.filter((node) => node.wireRef).map((node) => [node.wireRef, node.ref]));
+    const structuralGroups = new Map();
+    for (const node of base.nodes) {
+        const key = structuralKey(node);
+        structuralGroups.set(key, [...(structuralGroups.get(key) ?? []), node]);
+    }
+    let nextIndex = Math.max(0, ...base.nodes.map((node) => numericRef(node.ref))) + 1;
+    for (const node of next.nodes) {
+        const wireStable = node.wireRef ? byWireRef.get(node.wireRef) : undefined;
+        const structuralMatches = structuralGroups.get(structuralKey(node)) ?? [];
+        const stable = wireStable ?? (structuralMatches.length === 1 ? structuralMatches[0].ref : undefined);
+        if (stable && !reserved.has(stable)) {
+            node.ref = stable;
+            reserved.add(stable);
+            assigned.add(node);
+        }
+    }
+    for (const node of next.nodes) {
+        if (assigned.has(node))
+            continue;
+        while (reserved.has(`@e${nextIndex}`))
+            nextIndex += 1;
+        node.ref = `@e${nextIndex++}`;
+        reserved.add(node.ref);
+    }
+    rebuildIndexes(next);
+    return next;
+}
+function comparable(node) {
+    const { children: _children, ...fields } = serializeOutlineNode(node);
+    return {
+        ...fields,
+        rect: fields.rect
+            ? {
+                x: Math.round(fields.rect.x),
+                y: Math.round(fields.rect.y),
+                w: Math.round(fields.rect.w),
+                h: Math.round(fields.rect.h),
+            }
+            : undefined,
+        text: fields.text.map((item) => ({ string: item.string, confidence: Math.round(item.confidence * 100) / 100 })),
+    };
+}
+function changedFields(base, next) {
+    const before = comparable(base);
+    const after = comparable(next);
+    const fields = {};
+    for (const key of Object.keys(after)) {
+        if (key === "ref" || key === "wireRef")
+            continue;
+        if (JSON.stringify(before[key]) !== JSON.stringify(after[key]))
+            fields[key] = after[key];
+    }
+    return fields;
+}
+function refPath(node) {
+    const refs = [];
+    let current = node;
+    while (current) {
+        refs.unshift(current.ref);
+        current = current.parent;
+    }
+    return refs;
+}
+export function changesBetween(base, next) {
+    if (base.root.role !== next.root.role || base.root.subrole !== next.root.subrole) {
+        return {
+            changes: [],
+            changedNodeCount: next.nodes.length,
+            fullNodeCount: next.nodes.length,
+            useFullView: true,
+            reason: "root_replaced",
+        };
+    }
+    const before = new Map(base.nodes.map((node) => [node.ref, node]));
+    const after = new Map(next.nodes.map((node) => [node.ref, node]));
+    const changes = [];
+    for (const node of next.nodes) {
+        const previous = before.get(node.ref);
+        if (!previous)
+            changes.push({
+                type: "added",
+                ref: node.ref,
+                parent: node.parent?.ref,
+                node: { ...serializeOutlineNode(node), children: [] },
+            });
+        else {
+            const fields = changedFields(previous, node);
+            if (Object.keys(fields).length > 0)
+                changes.push({ type: "updated", ref: node.ref, path: refPath(node), fields });
+        }
+    }
+    for (const node of base.nodes)
+        if (!after.has(node.ref))
+            changes.push({ type: "removed", ref: node.ref, parent: node.parent?.ref });
+    const identityConfidence = next.nodes.length === 0 ? 1 : next.nodes.filter((node) => before.has(node.ref)).length / next.nodes.length;
+    const changeRatio = changes.length / Math.max(1, Math.max(base.nodes.length, next.nodes.length));
+    const identityLow = next.nodes.length > 8 && identityConfidence < 0.4;
+    const overBudget = changes.length > 100 || (changes.length > 20 && changeRatio > 0.65);
+    return {
+        changes,
+        changedNodeCount: changes.length,
+        fullNodeCount: next.nodes.length,
+        useFullView: identityLow || overBudget,
+        reason: identityLow ? "identity_confidence_low" : overBudget ? "change_budget_exceeded" : undefined,
+    };
+}
+function label(node) {
+    return (node.title ||
+        node.description ||
+        node.value ||
+        node.identifier ||
+        node.text
+            .map((item) => item.string)
+            .join(" ")
+            .trim() ||
+        node.role ||
+        "node");
+}
+export function renderChanges(changes) {
+    return changes
+        .map((change) => {
+        if (change.type === "added")
+            return `+ ${change.ref}${change.parent ? ` under ${change.parent}` : ""} ${JSON.stringify(label(change.node))}`;
+        if (change.type === "removed")
+            return `- ${change.ref}${change.parent ? ` from ${change.parent}` : ""}`;
+        const fields = Object.entries(change.fields)
+            .filter(([key]) => !["rect", "text", "actions"].includes(key))
+            .slice(0, 6)
+            .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+            .join(", ");
+        const supplemental = [
+            change.fields.text ? `text=${JSON.stringify(change.fields.text.map((item) => item.string))}` : undefined,
+            change.fields.actions ? `actions=${JSON.stringify(change.fields.actions)}` : undefined,
+        ]
+            .filter(Boolean)
+            .join(", ");
+        return `~ ${change.ref} (${change.path.join(" > ")}) ${[fields, supplemental].filter(Boolean).join(", ") || "changed"}`;
+    })
+        .join("\n");
+}
+//# sourceMappingURL=view.js.map

package/dist/core/computer/motor/view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../../../../src/core/computer/motor/view.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype Outline,\n\ttype OutlineChange,\n\ttype OutlineDiff,\n\ttype OutlineNode,\n\ttype SerializedOutlineNode,\n\tserializeOutlineNode,\n} from \"./outline.ts\";\n\nfunction numericRef(ref: string): number {\n\tconst match = /^@e(\\d+)$/.exec(ref);\n\treturn match ? Number(match[1]) : 0;\n}\n\nfunction rebuildIndexes(outline: Outline): void {\n\toutline.nodes = [];\n\toutline.refToWireRef = new Map();\n\toutline.wireRefToRef = new Map();\n\tconst queue = [outline.root];\n\twhile (queue.length > 0) {\n\t\tconst node = queue.shift()!;\n\t\toutline.nodes.push(node);\n\t\tif (node.wireRef) {\n\t\t\toutline.refToWireRef.set(node.ref, node.wireRef);\n\t\t\toutline.wireRefToRef.set(node.wireRef, node.ref);\n\t\t}\n\t\tqueue.push(...node.children);\n\t}\n}\n\nfunction structuralToken(node: OutlineNode): string {\n\treturn [node.role, node.subrole, node.identifier, node.title, node.description]\n\t\t.map((value) => value.trim().toLowerCase())\n\t\t.join(\"|\");\n}\n\nfunction structuralKey(node: OutlineNode): string {\n\tconst parts: string[] = [];\n\tlet current: OutlineNode | undefined = node;\n\twhile (current) {\n\t\tconst token = structuralToken(current);\n\t\tconst siblings = current.parent?.children ?? [current];\n\t\tconst peers = siblings.filter((candidate) => structuralToken(candidate) === token);\n\t\tparts.unshift(`${token}#${Math.max(0, peers.indexOf(current))}`);\n\t\tcurrent = current.parent;\n\t}\n\treturn parts.join(\">\");\n}\n\n/** Preserve public refs only when native or structural identity is unambiguous. */\nexport function stabilizeRefs(base: Outline | undefined, next: Outline): Outline {\n\tif (!base) return next;\n\tconst reserved = new Set<string>();\n\tconst assigned = new Set<OutlineNode>();\n\tconst byWireRef = new Map(base.nodes.filter((node) => node.wireRef).map((node) => [node.wireRef!, node.ref]));\n\tconst structuralGroups = new Map<string, OutlineNode[]>();\n\tfor (const node of base.nodes) {\n\t\tconst key = structuralKey(node);\n\t\tstructuralGroups.set(key, [...(structuralGroups.get(key) ?? []), node]);\n\t}\n\tlet nextIndex = Math.max(0, ...base.nodes.map((node) => numericRef(node.ref))) + 1;\n\tfor (const node of next.nodes) {\n\t\tconst wireStable = node.wireRef ? byWireRef.get(node.wireRef) : undefined;\n\t\tconst structuralMatches = structuralGroups.get(structuralKey(node)) ?? [];\n\t\tconst stable = wireStable ?? (structuralMatches.length === 1 ? structuralMatches[0].ref : undefined);\n\t\tif (stable && !reserved.has(stable)) {\n\t\t\tnode.ref = stable;\n\t\t\treserved.add(stable);\n\t\t\tassigned.add(node);\n\t\t}\n\t}\n\tfor (const node of next.nodes) {\n\t\tif (assigned.has(node)) continue;\n\t\twhile (reserved.has(`@e${nextIndex}`)) nextIndex += 1;\n\t\tnode.ref = `@e${nextIndex++}`;\n\t\treserved.add(node.ref);\n\t}\n\trebuildIndexes(next);\n\treturn next;\n}\n\nfunction comparable(node: OutlineNode): Omit<SerializedOutlineNode, \"children\"> {\n\tconst { children: _children, ...fields } = serializeOutlineNode(node);\n\treturn {\n\t\t...fields,\n\t\trect: fields.rect\n\t\t\t? {\n\t\t\t\t\tx: Math.round(fields.rect.x),\n\t\t\t\t\ty: Math.round(fields.rect.y),\n\t\t\t\t\tw: Math.round(fields.rect.w),\n\t\t\t\t\th: Math.round(fields.rect.h),\n\t\t\t\t}\n\t\t\t: undefined,\n\t\ttext: fields.text.map((item) => ({ string: item.string, confidence: Math.round(item.confidence * 100) / 100 })),\n\t};\n}\n\nfunction changedFields(base: OutlineNode, next: OutlineNode): Partial<Omit<SerializedOutlineNode, \"children\">> {\n\tconst before = comparable(base);\n\tconst after = comparable(next);\n\tconst fields: Partial<Omit<SerializedOutlineNode, \"children\">> = {};\n\tfor (const key of Object.keys(after) as Array<keyof typeof after>) {\n\t\tif (key === \"ref\" || key === \"wireRef\") continue;\n\t\tif (JSON.stringify(before[key]) !== JSON.stringify(after[key]))\n\t\t\t(fields as Record<string, unknown>)[key] = after[key];\n\t}\n\treturn fields;\n}\n\nfunction refPath(node: OutlineNode): string[] {\n\tconst refs: string[] = [];\n\tlet current: OutlineNode | undefined = node;\n\twhile (current) {\n\t\trefs.unshift(current.ref);\n\t\tcurrent = current.parent;\n\t}\n\treturn refs;\n}\n\nexport function changesBetween(base: Outline, next: Outline): OutlineDiff {\n\tif (base.root.role !== next.root.role || base.root.subrole !== next.root.subrole) {\n\t\treturn {\n\t\t\tchanges: [],\n\t\t\tchangedNodeCount: next.nodes.length,\n\t\t\tfullNodeCount: next.nodes.length,\n\t\t\tuseFullView: true,\n\t\t\treason: \"root_replaced\",\n\t\t};\n\t}\n\tconst before = new Map(base.nodes.map((node) => [node.ref, node]));\n\tconst after = new Map(next.nodes.map((node) => [node.ref, node]));\n\tconst changes: OutlineChange[] = [];\n\tfor (const node of next.nodes) {\n\t\tconst previous = before.get(node.ref);\n\t\tif (!previous)\n\t\t\tchanges.push({\n\t\t\t\ttype: \"added\",\n\t\t\t\tref: node.ref,\n\t\t\t\tparent: node.parent?.ref,\n\t\t\t\tnode: { ...serializeOutlineNode(node), children: [] },\n\t\t\t});\n\t\telse {\n\t\t\tconst fields = changedFields(previous, node);\n\t\t\tif (Object.keys(fields).length > 0)\n\t\t\t\tchanges.push({ type: \"updated\", ref: node.ref, path: refPath(node), fields });\n\t\t}\n\t}\n\tfor (const node of base.nodes)\n\t\tif (!after.has(node.ref)) changes.push({ type: \"removed\", ref: node.ref, parent: node.parent?.ref });\n\tconst identityConfidence =\n\t\tnext.nodes.length === 0 ? 1 : next.nodes.filter((node) => before.has(node.ref)).length / next.nodes.length;\n\tconst changeRatio = changes.length / Math.max(1, Math.max(base.nodes.length, next.nodes.length));\n\tconst identityLow = next.nodes.length > 8 && identityConfidence < 0.4;\n\tconst overBudget = changes.length > 100 || (changes.length > 20 && changeRatio > 0.65);\n\treturn {\n\t\tchanges,\n\t\tchangedNodeCount: changes.length,\n\t\tfullNodeCount: next.nodes.length,\n\t\tuseFullView: identityLow || overBudget,\n\t\treason: identityLow ? \"identity_confidence_low\" : overBudget ? \"change_budget_exceeded\" : undefined,\n\t};\n}\n\nfunction label(node: SerializedOutlineNode): string {\n\treturn (\n\t\tnode.title ||\n\t\tnode.description ||\n\t\tnode.value ||\n\t\tnode.identifier ||\n\t\tnode.text\n\t\t\t.map((item) => item.string)\n\t\t\t.join(\" \")\n\t\t\t.trim() ||\n\t\tnode.role ||\n\t\t\"node\"\n\t);\n}\n\nexport function renderChanges(changes: OutlineChange[]): string {\n\treturn changes\n\t\t.map((change) => {\n\t\t\tif (change.type === \"added\")\n\t\t\t\treturn `+ ${change.ref}${change.parent ? ` under ${change.parent}` : \"\"} ${JSON.stringify(label(change.node))}`;\n\t\t\tif (change.type === \"removed\") return `- ${change.ref}${change.parent ? ` from ${change.parent}` : \"\"}`;\n\t\t\tconst fields = Object.entries(change.fields)\n\t\t\t\t.filter(([key]) => ![\"rect\", \"text\", \"actions\"].includes(key))\n\t\t\t\t.slice(0, 6)\n\t\t\t\t.map(([key, value]) => `${key}=${JSON.stringify(value)}`)\n\t\t\t\t.join(\", \");\n\t\t\tconst supplemental = [\n\t\t\t\tchange.fields.text ? `text=${JSON.stringify(change.fields.text.map((item) => item.string))}` : undefined,\n\t\t\t\tchange.fields.actions ? `actions=${JSON.stringify(change.fields.actions)}` : undefined,\n\t\t\t]\n\t\t\t\t.filter(Boolean)\n\t\t\t\t.join(\", \");\n\t\t\treturn `~ ${change.ref} (${change.path.join(\" > \")}) ${[fields, supplemental].filter(Boolean).join(\", \") || \"changed\"}`;\n\t\t})\n\t\t.join(\"\\n\");\n}\n"]}

package/dist/core/computer/motor-ada.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Puente entre nuestras tools y el motor forkeado.
+ *
+ * Sustituye al driver anterior, que hablaba por CLI con `open-computer-use`.
+ * Aquel motor tenía seis acciones y le faltaban las dos que importan: esperar a
+ * que algo cambie, y buscar dentro de la interfaz. Sin espera se actúa sobre
+ * ventanas que aún no están listas — el fallo que apareció al probarlo contra
+ * TextEdit, donde la escritura se dio por buena y el fichero quedó vacío.
+ *
+ * El modelo del motor nuevo trae una garantía que antes no teníamos: **para
+ * actuar hace falta el `lookId` de una observación previa**. Nuestra guía "lee
+ * antes de pulsar" deja de ser un consejo en el prompt y pasa a ser un
+ * requisito que el motor impone. Actuar sobre estado viejo ya no compila.
+ *
+ * Aquí NO vive ninguna regla de permisos: eso es `politica.ts`, y lo aplica
+ * `tools.ts` antes de llamar a nada de esto.
+ */
+import { type Outline } from "./motor/outline.ts";
+import type { HelperActResult } from "./motor/platform/types.ts";
+/** Una observación viva. El `lookId` es lo que autoriza a actuar. */
+export interface Observacion {
+    lookId: string;
+    pid?: number;
+    /** Título de la ventana observada, para que el agente sepa dónde está. */
+    titulo?: string;
+    /** Texto legible del árbol, tal y como lo devuelve el motor. */
+    resumen: string;
+    elementos: number;
+    /**
+     * El árbol indexado. NO se le enseña al agente: es para comprobar por
+     * nuestra cuenta si una acción surtió efecto, sin fiarnos de lo que diga el
+     * motor. Ver `actuar`.
+     */
+    arbol?: Outline;
+    /** Captura de la ventana, solo si se pidió `conImagen`. */
+    imagen?: {
+        datos: string;
+        mimeType: string;
+    };
+}
+/**
+ * Arranca el demonio nativo si hace falta.
+ *
+ * Es idempotente y se llama antes de cada operación: el demonio puede haberse
+ * caído entre dos acciones, y descubrirlo con un ENOENT de socket es peor que
+ * volver a levantarlo.
+ */
+export declare function asegurarMotor(): Promise<void>;
+export interface AppAbierta {
+    nombre: string;
+    bundleId?: string;
+    pid?: number;
+}
+export declare function listarApps(signal?: AbortSignal): Promise<AppAbierta[]>;
+export declare function appEnPrimerPlano(signal?: AbortSignal): Promise<AppAbierta>;
+/** Localiza el pid de una aplicación por su nombre. */
+export declare function pidDe(nombreApp: string, signal?: AbortSignal): Promise<number | undefined>;
+/**
+ * Observa una ventana y devuelve la observación con la que se puede actuar.
+ *
+ * `readText: "auto"` deja al motor decidir cuánto texto trae: pedir siempre
+ * todo el texto de una ventana grande llena el contexto de ruido, y no pedirlo
+ * nunca obliga a una segunda llamada para cada etiqueta.
+ */
+export declare function observar(pid: number, opciones?: {
+    scopeRef?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    conImagen?: boolean;
+}): Promise<Observacion>;
+export type AccionMotor = {
+    tipo: "click";
+    ref: string;
+    boton?: "left" | "right" | "middle";
+    veces?: number;
+} | {
+    tipo: "escribir";
+    ref: string;
+    texto: string;
+} | {
+    tipo: "teclas";
+    ref?: string;
+    teclas: string[];
+} | {
+    tipo: "desplazar";
+    ref: string;
+    x: number;
+    y: number;
+};
+/**
+ * Actúa sobre una observación.
+ *
+ * Exige el `lookId`: el motor rechaza actuar sobre una observación que ya no
+ * refleja la pantalla. Eso convierte en imposible el fallo de escribir en una
+ * ventana que se cerró en medio.
+ */
+export declare function actuar(observacion: Observacion, accion: AccionMotor, opciones?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<{
+    ok: boolean;
+    detalle: string;
+}>;
+/**
+ * Traduce la respuesta del motor a "¿pasó o no pasó?".
+ *
+ * El motor NO responde con un booleano: responde con `outcome`, que tiene tres
+ * valores. Y el tercero es el que importa:
+ *
+ * - `worked`  — lo hizo y lo comprobó.
+ * - `didnt`   — lo intentó y NO surtió efecto. Sin error: el clic salió, la
+ *               interfaz no se movió.
+ * - `unknown` — lo hizo pero no pudo verificarlo.
+ *
+ * Tratar `didnt` como éxito es justo el fallo que motivó cambiar de motor: se
+ * dio por escrito un texto y el fichero quedó vacío. Solo `worked` es un sí.
+ * `unknown` se devuelve como fallo A PROPÓSITO, diciendo que no se pudo
+ * comprobar: es preferible que el agente vuelva a mirar con `computer_read` a
+ * que encadene diez acciones sobre una suposición.
+ *
+ * Es una función aparte, y pura, para poder probar los tres casos sin un
+ * ordenador delante — el motivo por el que el fallo anterior sobrevivió es que
+ * esto vivía dentro de una llamada al sistema que las pruebas nunca alcanzaban.
+ */
+export declare function interpretarResultado(r: HelperActResult): {
+    ok: boolean;
+    detalle: string;
+};
+/**
+ * Espera a que algo aparezca (o desaparezca) en una ventana.
+ *
+ * Es la pieza por la que se cambió de motor. Sin ella, la única forma de
+ * "esperar" era dormir un rato fijo y cruzar los dedos: demasiado corto falla,
+ * demasiado largo desperdicia el turno, y ninguno de los dos sabe si lo que
+ * esperabas llegó.
+ */
+export declare function esperar(pid: number, criterio: {
+    texto?: string;
+    rol?: string;
+    desaparezca?: boolean;
+    timeoutMs?: number;
+}, opciones?: {
+    signal?: AbortSignal;
+}): Promise<{
+    encontrado: boolean;
+    detalle: string;
+}>;
+/** Lee el texto de un elemento, por trozos. */
+export declare function leerTexto(observacion: Observacion, elementRef: string, opciones?: {
+    offset?: number;
+    limit?: number;
+    signal?: AbortSignal;
+}): Promise<{
+    texto: string;
+    hayMas: boolean;
+    total: number;
+}>;
+export declare function cerrarMotor(): void;
+//# sourceMappingURL=motor-ada.d.ts.map

package/dist/core/computer/motor-ada.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"motor-ada.d.ts","sourceRoot":"","sources":["../../../src/core/computer/motor-ada.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Puente entre nuestras tools y el motor forkeado.\n *\n * Sustituye al driver anterior, que hablaba por CLI con `open-computer-use`.\n * Aquel motor tenía seis acciones y le faltaban las dos que importan: esperar a\n * que algo cambie, y buscar dentro de la interfaz. Sin espera se actúa sobre\n * ventanas que aún no están listas — el fallo que apareció al probarlo contra\n * TextEdit, donde la escritura se dio por buena y el fichero quedó vacío.\n *\n * El modelo del motor nuevo trae una garantía que antes no teníamos: **para\n * actuar hace falta el `lookId` de una observación previa**. Nuestra guía \"lee\n * antes de pulsar\" deja de ser un consejo en el prompt y pasa a ser un\n * requisito que el motor impone. Actuar sobre estado viejo ya no compila.\n *\n * Aquí NO vive ninguna regla de permisos: eso es `politica.ts`, y lo aplica\n * `tools.ts` antes de llamar a nada de esto.\n */\n\nimport { countOutlineNodes, foldToBudget, type LookResponse, nodeByRef, type Outline } from \"./motor/outline.ts\";\nimport { currentPlatformBackend } from \"./motor/platform/index.ts\";\nimport { macosHelper } from \"./motor/platform/macos/helper.ts\";\nimport type { HelperActResult, PlatformActRequest } from \"./motor/platform/types.ts\";\nimport { scoreWindow } from \"./motor/root-selection.ts\";\n\n/** Una observación viva. El `lookId` es lo que autoriza a actuar. */\nexport interface Observacion {\n\tlookId: string;\n\tpid?: number;\n\t/** Título de la ventana observada, para que el agente sepa dónde está. */\n\ttitulo?: string;\n\t/** Texto legible del árbol, tal y como lo devuelve el motor. */\n\tresumen: string;\n\telementos: number;\n\t/**\n\t * El árbol indexado. NO se le enseña al agente: es para comprobar por\n\t * nuestra cuenta si una acción surtió efecto, sin fiarnos de lo que diga el\n\t * motor. Ver `actuar`.\n\t */\n\tarbol?: Outline;\n\t/** Captura de la ventana, solo si se pidió `conImagen`. */\n\timagen?: { datos: string; mimeType: string };\n}\n\nlet arrancado = false;\n\n/**\n * Arranca el demonio nativo si hace falta.\n *\n * Es idempotente y se llama antes de cada operación: el demonio puede haberse\n * caído entre dos acciones, y descubrirlo con un ENOENT de socket es peor que\n * volver a levantarlo.\n */\nexport async function asegurarMotor(): Promise<void> {\n\tif (process.platform !== \"darwin\") return;\n\tif (arrancado) return;\n\tawait macosHelper.ensureInstalled();\n\tawait macosHelper.ensureDaemon();\n\tarrancado = true;\n}\n\nexport interface AppAbierta {\n\tnombre: string;\n\tbundleId?: string;\n\tpid?: number;\n}\n\nexport async function listarApps(signal?: AbortSignal): Promise<AppAbierta[]> {\n\tawait asegurarMotor();\n\tconst apps = await currentPlatformBackend.listApps(signal);\n\treturn apps.map((a) => ({\n\t\tnombre: (a as { appName?: string }).appName ?? (a as { bundleId?: string }).bundleId ?? \"(sin nombre)\",\n\t\tbundleId: (a as { bundleId?: string }).bundleId,\n\t\tpid: (a as { pid?: number }).pid,\n\t}));\n}\n\nexport async function appEnPrimerPlano(signal?: AbortSignal): Promise<AppAbierta> {\n\tawait asegurarMotor();\n\tconst f = (await currentPlatformBackend.getFrontmost(signal)) as {\n\t\tappName?: string;\n\t\tbundleId?: string;\n\t\tpid?: number;\n\t};\n\treturn { nombre: f.appName ?? \"(desconocida)\", bundleId: f.bundleId, pid: f.pid };\n}\n\n/** Localiza el pid de una aplicación por su nombre. */\nexport async function pidDe(nombreApp: string, signal?: AbortSignal): Promise<number | undefined> {\n\tconst apps = await listarApps(signal);\n\tconst buscado = nombreApp.trim().toLowerCase();\n\treturn apps.find((a) => a.nombre.trim().toLowerCase() === buscado)?.pid;\n}\n\n/**\n * Por qué una aplicación viva no enseña ninguna ventana.\n *\n * Hay dos motivos y se parecen desde fuera: o de verdad no tiene ventanas, o\n * macOS nos está negando la Accesibilidad y por eso el árbol llega vacío.\n *\n * Distinguirlos no es cosmético. Se descubrió probándolo: con los permisos sin\n * conceder, `computer_read` sobre TextEdit —que estaba abierto y salía en la\n * lista de aplicaciones— contestaba \"no tiene ninguna ventana abierta\". Un\n * agente que lea eso intentará ABRIR una ventana, que no arregla nada. El error\n * no solo era inútil: empujaba en la dirección contraria.\n *\n * Solo se pregunta al fallar, no en cada observación: el diagnóstico cuesta una\n * ida y vuelta al helper y el caso normal es que haya ventanas.\n */\nasync function porQueNoHayVentanas(pid: number, signal?: AbortSignal): Promise<string> {\n\tconst sinVentanas = `El proceso ${pid} no tiene ninguna ventana abierta. Puede estar en segundo plano o minimizado.`;\n\tif (process.platform !== \"darwin\") return sinVentanas;\n\ttry {\n\t\tconst d = (await macosHelper.diagnosticsCommand(signal)) as { accessibility?: boolean };\n\t\tif (d.accessibility === true) return sinVentanas;\n\t\treturn (\n\t\t\t`macOS está negando el permiso de Accesibilidad, así que no se puede leer la interfaz de ninguna ` +\n\t\t\t`aplicación (el proceso ${pid} sí está vivo). Concédelo con 'ada-cli computer permissions', o en ` +\n\t\t\t`Ajustes del Sistema → Privacidad y seguridad → Accesibilidad.`\n\t\t);\n\t} catch {\n\t\t// Si ni el diagnóstico contesta, no se inventa un motivo.\n\t\treturn sinVentanas;\n\t}\n}\n\n/**\n * Traduce un fallo de captura a algo accionable.\n *\n * Leer una ventana necesita LOS DOS permisos, no solo Accesibilidad: el motor\n * captura para situar los elementos. Con la Accesibilidad concedida y la\n * Grabación de pantalla no, macOS devuelve \"El usuario ha rechazado las\n * preferencias de TCC para la captura…\" — que dice la causa y ningún remedio, y\n * además contradice lo que el usuario acaba de hacer (conceder un permiso).\n *\n * Se detecta por el texto porque es lo que hay: el error llega como cadena del\n * sistema, traducida al idioma del Mac. Por eso se buscan las dos palabras que\n * no cambian de forma —TCC y capture/captura— en vez de una frase entera.\n */\nfunction explicarFalloDeCaptura(error: unknown): string {\n\tconst mensaje = error instanceof Error ? error.message : String(error);\n\tconst esTcc = /\\bTCC\\b/i.test(mensaje) || /captur/i.test(mensaje);\n\tif (!esTcc) return mensaje;\n\treturn (\n\t\t`${mensaje}\\n\\n` +\n\t\t`Leer una ventana necesita TAMBIÉN el permiso de Grabación de pantalla, no solo el de ` +\n\t\t`Accesibilidad: el motor captura la pantalla para situar los elementos. Ábrelo con ` +\n\t\t`'ada-cli computer permissions' y, después de concederlo, 'ada-cli computer recheck' — ` +\n\t\t`macOS cachea los permisos por proceso y hasta que el motor no se reinicie seguirá creyendo ` +\n\t\t`que no lo tiene.`\n\t);\n}\n\n/**\n * Observa una ventana y devuelve la observación con la que se puede actuar.\n *\n * `readText: \"auto\"` deja al motor decidir cuánto texto trae: pedir siempre\n * todo el texto de una ventana grande llena el contexto de ruido, y no pedirlo\n * nunca obliga a una segunda llamada para cada etiqueta.\n */\nexport async function observar(\n\tpid: number,\n\topciones: { scopeRef?: string; signal?: AbortSignal; timeoutMs?: number; conImagen?: boolean } = {},\n): Promise<Observacion> {\n\tawait asegurarMotor();\n\n\t// Hay que resolver la VENTANA primero. Observar por pid a secas falla con\n\t// \"Root is not owned by a running app\": un proceso puede tener cero, una o\n\t// diez ventanas, y el motor necesita saber cuál.\n\tconst raices = await currentPlatformBackend.listRoots({ pid }, opciones.signal);\n\tif (raices.length === 0) throw new Error(await porQueNoHayVentanas(pid, opciones.signal));\n\n\t// Estar minimizada se FILTRA, no se puntúa. Es una precondición, no una\n\t// preferencia: una ventana minimizada no se puede observar en absoluto.\n\t//\n\t// Esto no es teórico. `scoreWindow` (del propio motor) da +180 a `isModal`,\n\t// más que a todo lo demás junto, y las ventanas de TextEdit se declaran\n\t// `AXDialog` → modales. Resultado con TextEdit abierto: una ventana\n\t// minimizada ganaba a la única usable, y el motor contestaba \"Root is not\n\t// owned by a running app\" — que no menciona ni ventanas ni minimizado. El\n\t// propio `root-selection.ts` avisa de la trampa: \"AXDialog can describe a\n\t// background main window, so modality alone is insufficient\".\n\t//\n\t// Entre las que SÍ sirven, `scoreWindow` ordena bien: foco, principal, en\n\t// pantalla. Ahí sí es preferencia.\n\tconst usables = raices.filter((r) => !r.isMinimized);\n\tconst [raiz] = (usables.length > 0 ? usables : raices).sort((a, b) => scoreWindow(b) - scoreWindow(a));\n\tif (usables.length === 0) {\n\t\t// Todas minimizadas: es un estado del que el agente PUEDE salir, pero solo\n\t\t// si se lo dicen. El error del motor no lo menciona.\n\t\tconst cuales = raices\n\t\t\t.map((r) => `\"${r.title}\"`)\n\t\t\t.slice(0, 5)\n\t\t\t.join(\", \");\n\t\tthrow new Error(\n\t\t\t`Todas las ventanas de este proceso están minimizadas (${cuales}), y una ventana minimizada no se puede leer. ` +\n\t\t\t\t`Pídele al usuario que la restaure, o abre la aplicación desde el Dock.`,\n\t\t);\n\t}\n\n\tlet r: LookResponse;\n\ttry {\n\t\tr = (await currentPlatformBackend.observe(\n\t\t\t{\n\t\t\t\ttarget: { pid, windowId: raiz.windowId },\n\t\t\t\treadText: \"auto\",\n\t\t\t\tscopeRef: opciones.scopeRef,\n\t\t\t\tincludeImage: opciones.conImagen === true,\n\t\t\t},\n\t\t\t{ signal: opciones.signal, timeoutMs: opciones.timeoutMs },\n\t\t)) as LookResponse;\n\t} catch (error) {\n\t\tthrow new Error(explicarFalloDeCaptura(error));\n\t}\n\n\t// `outline` NO es texto: es el árbol, con referencias al padre en cada nodo.\n\t// Un `JSON.stringify` revienta con \"circular structure\" — y solo revienta\n\t// cuando hay permisos, porque sin ellos nunca se llega hasta aquí.\n\t//\n\t// El motor trae su propio renderizador, `foldToBudget`, que además PLIEGA:\n\t// una ventana real tiene miles de nodos y volcarlos todos llenaría el\n\t// contexto de ruido dejando lo importante enterrado. Se despliega lo que\n\t// tiene el foco y lo accionable, se pliega el resto.\n\t// `parsedOutline` es el árbol INDEXADO (con el mapa de referencias); `outline`\n\t// a secas es solo el nodo raíz, que no basta para plegar. El backend lo rellena\n\t// al parsear la respuesta del helper.\n\tconst arbol = r.parsedOutline;\n\treturn {\n\t\tlookId: r.lookId ?? \"\",\n\t\tpid,\n\t\ttitulo: raiz.title,\n\t\tresumen: arbol ? foldToBudget(arbol).text : \"(el motor no devolvió ningún árbol)\",\n\t\telementos: countOutlineNodes(r.outline),\n\t\tarbol,\n\t\timagen: r.image ? { datos: r.image.jpegBase64, mimeType: r.image.mimeType ?? \"image/jpeg\" } : undefined,\n\t};\n}\n\nexport type AccionMotor =\n\t| { tipo: \"click\"; ref: string; boton?: \"left\" | \"right\" | \"middle\"; veces?: number }\n\t| { tipo: \"escribir\"; ref: string; texto: string }\n\t| { tipo: \"teclas\"; ref?: string; teclas: string[] }\n\t| { tipo: \"desplazar\"; ref: string; x: number; y: number };\n\n/**\n * Actúa sobre una observación.\n *\n * Exige el `lookId`: el motor rechaza actuar sobre una observación que ya no\n * refleja la pantalla. Eso convierte en imposible el fallo de escribir en una\n * ventana que se cerró en medio.\n */\nexport async function actuar(\n\tobservacion: Observacion,\n\taccion: AccionMotor,\n\topciones: { signal?: AbortSignal; timeoutMs?: number } = {},\n): Promise<{ ok: boolean; detalle: string }> {\n\tawait asegurarMotor();\n\n\t// Tipado explícito y SIN casts: es la única comprobación automática de que\n\t// los nombres de acción que enviamos existen de verdad en el motor. El\n\t// `screenshot` fantasma del motor anterior sobrevivió a las pruebas porque\n\t// aquella llamada iba por texto libre; aquí un nombre inventado no compila.\n\tconst construir = (politica: \"background\" | \"foreground\"): PlatformActRequest => {\n\t\t// El motor deriva el transporte de la política: en primer plano manda\n\t\t// eventos HID (como un teclado de verdad), en segundo plano los entrega al\n\t\t// proceso. Sin este campo la entrega queda a medias y la escritura se\n\t\t// acepta sin surtir efecto.\n\t\tconst delivery = politica === \"foreground\" ? (\"hid\" as const) : (\"pid\" as const);\n\t\tconst base = { lookId: observacion.lookId, pid: observacion.pid, policy: politica };\n\t\tswitch (accion.tipo) {\n\t\t\tcase \"click\":\n\t\t\t\treturn {\n\t\t\t\t\t...base,\n\t\t\t\t\ttarget: { ref: accion.ref },\n\t\t\t\t\taction: \"click\" as const,\n\t\t\t\t\tparams: { button: accion.boton ?? \"left\", clickCount: accion.veces ?? 1, delivery },\n\t\t\t\t};\n\t\t\tcase \"escribir\":\n\t\t\t\treturn {\n\t\t\t\t\t...base,\n\t\t\t\t\ttarget: { ref: accion.ref },\n\t\t\t\t\taction: \"typeText\" as const,\n\t\t\t\t\tparams: { text: accion.texto, delivery },\n\t\t\t\t};\n\t\t\tcase \"teclas\":\n\t\t\t\treturn {\n\t\t\t\t\t...base,\n\t\t\t\t\ttarget: accion.ref ? { ref: accion.ref } : { ref: \"\" },\n\t\t\t\t\taction: \"keypress\" as const,\n\t\t\t\t\tparams: { keys: accion.teclas, delivery },\n\t\t\t\t};\n\t\t\tcase \"desplazar\":\n\t\t\t\treturn {\n\t\t\t\t\t...base,\n\t\t\t\t\ttarget: { ref: accion.ref },\n\t\t\t\t\taction: \"scroll\" as const,\n\t\t\t\t\tparams: { scrollX: accion.x, scrollY: accion.y, delivery },\n\t\t\t\t};\n\t\t}\n\t};\n\n\t// Escribir tarda proporcionalmente a lo que se escribe. Un timeout fijo corta\n\t// los textos largos por la mitad, y medio texto escrito es peor que ninguno.\n\tconst texto = accion.tipo === \"escribir\" ? accion.texto : \"\";\n\tconst timeoutMs = opciones.timeoutMs ?? Math.max(15_000, texto.length * 25 + 4_000);\n\tconst ejecutar = (politica: \"background\" | \"foreground\") =>\n\t\tcurrentPlatformBackend.act(construir(politica), { signal: opciones.signal, timeoutMs });\n\n\t// Segundo plano PRIMERO. Es la diferencia entre trabajar mientras el usuario\n\t// usa su ordenador y robarle la ventana en cada acción.\n\t//\n\t// Pero el segundo plano falla en aplicaciones que exigen ser la de delante\n\t// para aceptar entrada — TextEdit entre ellas: el motor contesta \"the\n\t// background accessibility value write was accepted but did not take effect\".\n\t// Entonces se ESCALA a primer plano, que levanta la ventana y manda eventos\n\t// HID reales. Solo para escribir y teclas: repetir un clic podría pulsar dos\n\t// veces algo que ya funcionó, y esa es la asimetría que el propio motor fija\n\t// en `canRetryInForeground`.\n\tconst puedeEscalar = accion.tipo === \"escribir\" || accion.tipo === \"teclas\";\n\ttry {\n\t\tconst primero = await ejecutar(\"background\");\n\t\tif (primero.outcome !== \"didnt\" || !puedeEscalar) return interpretarResultado(primero);\n\n\t\t// ANTES de repetir, comprobarlo por nuestra cuenta.\n\t\t//\n\t\t// El motor decide `didnt` mirando su propia evidencia, y con TextEdit esa\n\t\t// evidencia es un FALSO NEGATIVO: dice `valueChanged: false, value: \"\"`\n\t\t// mientras el texto está escrito y se ve en el árbol. Escalando a ciegas\n\t\t// se escribía DOS VECES — \"HOLA'ADAHOLA'ADA\" en el documento de prueba.\n\t\t//\n\t\t// Y duplicar es peor que fallar: fallar se ve, duplicar no. Así que la\n\t\t// escalada solo ocurre si el valor del elemento sigue igual que antes. No\n\t\t// se compara con el texto pedido (la aplicación puede transformarlo — la\n\t\t// sustitución tipográfica de TextEdit convierte los guiones en comillas),\n\t\t// sino con el valor previo: cualquier cambio significa que entró.\n\t\tif (await yaSurtioEfecto(observacion, accion, opciones.signal)) {\n\t\t\treturn { ok: true, detalle: \"Hecho (el motor no pudo verificarlo, pero el valor cambió).\" };\n\t\t}\n\t\treturn interpretarResultado(await ejecutar(\"foreground\"));\n\t} catch (error) {\n\t\t// El motor pide primer plano explícitamente con este código.\n\t\tconst codigo = (error as { code?: string })?.code;\n\t\tif (codigo === \"foreground_required\") {\n\t\t\ttry {\n\t\t\t\treturn interpretarResultado(await ejecutar(\"foreground\"));\n\t\t\t} catch (segundo) {\n\t\t\t\treturn { ok: false, detalle: segundo instanceof Error ? segundo.message : String(segundo) };\n\t\t\t}\n\t\t}\n\t\treturn { ok: false, detalle: error instanceof Error ? error.message : String(error) };\n\t}\n}\n\n/**\n * Busca un nodo tolerando la arroba.\n *\n * En el árbol el ref se guarda como `\"@e10\"`, pero en el texto que ve el agente\n * aparece como `@e10` dentro de una línea, y tanto el agente como el motor\n * aceptan `e10` a secas. Es decir: hay dos formas del mismo identificador\n * circulando. El motor las normaliza al actuar; `nodeByRef` no, y devolvía\n * `undefined` en silencio — que en `yaSurtioEfecto` significaba \"no lo puedo\n * comprobar\" y disparaba la escalada. De ahí el texto duplicado.\n */\nfunction nodoDe(arbol: Outline, ref: string) {\n\tconst limpio = ref.replace(/^@/, \"\");\n\treturn nodeByRef(arbol, ref) ?? nodeByRef(arbol, `@${limpio}`) ?? nodeByRef(arbol, limpio);\n}\n\n/**\n * ¿Cambió el valor del elemento, aunque el motor diga que no?\n *\n * Se vuelve a observar y se compara el valor del MISMO ref con el que tenía en\n * la observación de partida. Cualquier diferencia cuenta como éxito: no se\n * compara con el texto que se pidió escribir porque la aplicación puede\n * transformarlo al vuelo.\n *\n * Ante la duda devuelve `false` — es decir, deja que se escale. Un fallo por\n * duplicar texto es silencioso; un fallo por no escribir se ve enseguida.\n */\nasync function yaSurtioEfecto(observacion: Observacion, accion: AccionMotor, signal?: AbortSignal): Promise<boolean> {\n\tif (accion.tipo !== \"escribir\" || !observacion.arbol || observacion.pid === undefined) return false;\n\tconst antes = nodoDe(observacion.arbol, accion.ref)?.value;\n\tif (antes === undefined) return false;\n\ttry {\n\t\tconst ahora = await observar(observacion.pid, { signal });\n\t\tconst despues = ahora.arbol ? nodoDe(ahora.arbol, accion.ref)?.value : undefined;\n\t\treturn despues !== undefined && despues !== antes;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/**\n * Traduce la respuesta del motor a \"¿pasó o no pasó?\".\n *\n * El motor NO responde con un booleano: responde con `outcome`, que tiene tres\n * valores. Y el tercero es el que importa:\n *\n * - `worked`  — lo hizo y lo comprobó.\n * - `didnt`   — lo intentó y NO surtió efecto. Sin error: el clic salió, la\n *               interfaz no se movió.\n * - `unknown` — lo hizo pero no pudo verificarlo.\n *\n * Tratar `didnt` como éxito es justo el fallo que motivó cambiar de motor: se\n * dio por escrito un texto y el fichero quedó vacío. Solo `worked` es un sí.\n * `unknown` se devuelve como fallo A PROPÓSITO, diciendo que no se pudo\n * comprobar: es preferible que el agente vuelva a mirar con `computer_read` a\n * que encadene diez acciones sobre una suposición.\n *\n * Es una función aparte, y pura, para poder probar los tres casos sin un\n * ordenador delante — el motivo por el que el fallo anterior sobrevivió es que\n * esto vivía dentro de una llamada al sistema que las pruebas nunca alcanzaban.\n */\nexport function interpretarResultado(r: HelperActResult): { ok: boolean; detalle: string } {\n\tconst cambios = (r.rootDelta ?? [])\n\t\t.map((d) => `${d.change}: ${d.title ?? d.kind}`)\n\t\t.slice(0, 5)\n\t\t.join(\"; \");\n\n\tif (r.outcome === \"worked\") {\n\t\treturn { ok: true, detalle: cambios ? `Hecho. Cambios en pantalla — ${cambios}` : \"Hecho.\" };\n\t}\n\n\tconst motivo = r.error?.message ?? r.error?.code;\n\tif (r.outcome === \"didnt\") {\n\t\treturn {\n\t\t\tok: false,\n\t\t\tdetalle: motivo\n\t\t\t\t? `La acción no surtió efecto: ${motivo}`\n\t\t\t\t: \"La acción no surtió efecto. El elemento puede estar deshabilitado, tapado o no aceptar esta acción.\",\n\t\t};\n\t}\n\n\treturn {\n\t\tok: false,\n\t\tdetalle: `No se pudo comprobar si la acción surtió efecto${motivo ? `: ${motivo}` : \"\"}. Vuelve a leer la ventana con computer_read antes de seguir.`,\n\t};\n}\n\n/**\n * Espera a que algo aparezca (o desaparezca) en una ventana.\n *\n * Es la pieza por la que se cambió de motor. Sin ella, la única forma de\n * \"esperar\" era dormir un rato fijo y cruzar los dedos: demasiado corto falla,\n * demasiado largo desperdicia el turno, y ninguno de los dos sabe si lo que\n * esperabas llegó.\n */\nexport async function esperar(\n\tpid: number,\n\tcriterio: { texto?: string; rol?: string; desaparezca?: boolean; timeoutMs?: number },\n\topciones: { signal?: AbortSignal } = {},\n): Promise<{ encontrado: boolean; detalle: string }> {\n\tawait asegurarMotor();\n\tconst timeoutMs = Math.min(Math.max(criterio.timeoutMs ?? 10_000, 500), 60_000);\n\ttry {\n\t\tconst r = (await currentPlatformBackend.waitFor(\n\t\t\t{ pid, text: criterio.texto, role: criterio.rol, gone: criterio.desaparezca === true, timeoutMs },\n\t\t\t{ signal: opciones.signal, timeoutMs: timeoutMs + 5_000 },\n\t\t)) as { found?: boolean; timedOut?: boolean };\n\t\treturn {\n\t\t\tencontrado: r.found === true,\n\t\t\tdetalle: r.found ? \"encontrado\" : r.timedOut ? `no apareció en ${timeoutMs} ms` : \"no encontrado\",\n\t\t};\n\t} catch (error) {\n\t\treturn { encontrado: false, detalle: error instanceof Error ? error.message : String(error) };\n\t}\n}\n\n/** Lee el texto de un elemento, por trozos. */\nexport async function leerTexto(\n\tobservacion: Observacion,\n\telementRef: string,\n\topciones: { offset?: number; limit?: number; signal?: AbortSignal } = {},\n): Promise<{ texto: string; hayMas: boolean; total: number }> {\n\tawait asegurarMotor();\n\tconst r = await currentPlatformBackend.readText(\n\t\t{\n\t\t\tlookId: observacion.lookId,\n\t\t\telementRef,\n\t\t\toffset: opciones.offset ?? 0,\n\t\t\tlimit: Math.min(opciones.limit ?? 4000, 20_000),\n\t\t},\n\t\t{ signal: opciones.signal },\n\t);\n\treturn { texto: r.text, hayMas: r.hasMore, total: r.totalChars };\n}\n\nexport function cerrarMotor(): void {\n\tarrancado = false;\n\tvoid currentPlatformBackend.shutdown?.();\n}\n"]}