@anuraghq/mobius 0.0.0-stage → 0.1.1

package/dist/execution/drivers/mobiusagent.js

@@ -0,0 +1,165 @@
+// Execution: the Mobius device driver (drivers/mobiusagent-driver, Rust). One long-lived process speaks JSON lines over stdio.
+// Android: stock adb + an on-device helper. iOS: WebDriverAgent over usbmuxd (once built with ios-agent/setup.sh).
+import { spawn } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+import { MobiusError } from "../connector.js";
+import { detectAndroidFramework, toRawNode } from "./nodes.js";
+/** The driver binary: $MOBIUS_DRIVER_BIN, the one bundled in the npm package for this platform, or a source build. */
+export const driverPath = () => {
+    if (process.env.MOBIUS_DRIVER_BIN)
+        return process.env.MOBIUS_DRIVER_BIN;
+    const bundled = fileURLToPath(new URL(`../../../bin/mobiusagent-driver-${process.platform}-${process.arch}`, import.meta.url));
+    return existsSync(bundled) ? bundled : fileURLToPath(new URL('../../../../../drivers/mobiusagent-driver/target/release/mobiusagent-driver', import.meta.url));
+};
+/** The driver binary is built (`cargo build --release` in drivers/mobiusagent-driver). */
+export const driverBuilt = () => existsSync(driverPath());
+/** iOS needs WebDriverAgent built and signed once (drivers/mobiusagent-driver/ios-agent/setup.sh). */
+export const iosAgentReady = () => {
+    const dir = join(process.env.MOBIUS_WDA_DIR ?? join(homedir(), '.mobius', 'wda'), 'build', 'Build', 'Products');
+    try {
+        return readdirSync(dir).some(f => f.endsWith('.xctestrun'));
+    }
+    catch {
+        return false;
+    }
+};
+export class MobiusAgentDriver {
+    proc = null;
+    next = 1;
+    waiting = new Map();
+    start() {
+        const p = spawn(driverPath(), [], { stdio: ['pipe', 'pipe', 'pipe'] });
+        createInterface({ input: p.stdout }).on('line', line => {
+            let r;
+            try {
+                r = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            const w = this.waiting.get(r.id);
+            if (!w)
+                return;
+            this.waiting.delete(r.id);
+            r.ok ? w.ok(r.data) : w.fail(new MobiusError('INTERNAL', String(r.error)));
+        });
+        p.on('exit', () => {
+            for (const w of this.waiting.values())
+                w.fail(new MobiusError('INTERNAL', 'mobiusagent-driver exited', { retryable: true }));
+            this.waiting.clear();
+            this.proc = null;
+        });
+        this.proc = p;
+        return p;
+    }
+    // 2 minutes: the first iOS read may have to start the runner (seconds directly, up to ~90 s through xcodebuild).
+    call(op, args = {}, timeoutMs = 120_000) {
+        const p = this.proc ?? this.start();
+        const id = this.next++;
+        return new Promise((ok, fail) => {
+            const t = setTimeout(() => {
+                this.waiting.delete(id);
+                // ponytail: a wedged adb call blocks the one driver process; restart it rather than queue behind it.
+                this.proc?.kill();
+                fail(new MobiusError('TIMEOUT', `mobiusagent-driver ${op} timed out`, { retryable: true }));
+            }, timeoutMs);
+            this.waiting.set(id, { ok: v => { clearTimeout(t); ok(v); }, fail: e => { clearTimeout(t); fail(e); } });
+            p.stdin.write(JSON.stringify({ id, op, ...args }) + '\n');
+        });
+    }
+    async devices() { return (await this.call('devices')).devices; }
+    close() { this.proc?.kill(); this.proc = null; }
+}
+const KEYS = { back: 'back', home: 'home', recents: 'recents', enter: 'enter' };
+export class MobiusAgentConnector {
+    platform;
+    deviceId;
+    capabilities = new Set([
+        'observe', 'screenshot', 'tap', 'type', 'swipe', 'scroll', 'press_key', 'list_apps', 'open_app', 'open_url', 'wait_for',
+    ]);
+    limitations;
+    size = null;
+    fwCache = new Map();
+    drv;
+    dev;
+    constructor(drv, dev) {
+        this.drv = drv;
+        this.dev = dev;
+        this.deviceId = dev.id;
+        this.platform = dev.platform;
+        this.limitations = [
+            'Interaction is coordinate-based (taps at element centres), not semantic accessibility actions.',
+            ...(dev.platform === 'ios'
+                ? ['iOS: real devices over USB with WebDriverAgent (developer setup). Back and Recents keys do not exist; use on-screen navigation.']
+                : ['Android: FLAG_SECURE screens screenshot as black.']),
+        ];
+    }
+    get virtual() { return this.dev.type === 'emulator' || this.dev.type === 'simulator'; }
+    get d() { return { device: this.dev.id }; }
+    async info() {
+        return { device_id: this.dev.id, platform: this.dev.platform, connector: 'mobiusagent-driver', name: this.dev.name, model: this.dev.model,
+            os_version: this.dev.version, online: this.dev.state === 'online', screen_on: null, locked: null };
+    }
+    async dump() {
+        const r = await this.drv.call('dump', this.d).catch(e => {
+            throw new MobiusError('DEVICE_LOCKED', `Could not read the screen: ${e.message}`, { retryable: true, hint: 'Ask the user to wake and unlock the phone.' });
+        });
+        this.size = { width: r.width, height: r.height };
+        const root = { cls: 'hierarchy', pkg: '', text: '', desc: '', resourceId: '', clickable: false, longClickable: false,
+            enabled: true, focused: false, scrollable: false, checkable: false, checked: false, selected: false, password: false,
+            bounds: { x: 0, y: 0, width: r.width, height: r.height }, path: 'r', children: [] };
+        r.tree.hierarchy.forEach((w, i) => { const n = toRawNode(w, `r.${i}`); if (n)
+            root.children.push(n); });
+        return { root, width: r.width, height: r.height, rotation: r.rotation, foregroundApp: r.foregroundApp };
+    }
+    async framework(pkg) {
+        if (this.platform === 'ios')
+            return 'unknown';
+        const hit = this.fwCache.get(pkg);
+        if (hit)
+            return hit;
+        const fw = await detectAndroidFramework(this.dev.id, pkg).catch(() => 'unknown');
+        this.fwCache.set(pkg, fw);
+        return fw;
+    }
+    async screenshot(maxSize) { return this.drv.call('screenshot', { ...this.d, max: maxSize }); }
+    async tap(x, y, mode) { await this.drv.call('tap', { ...this.d, x, y, mode }); }
+    async type(text, submit) {
+        await this.drv.call('text', { ...this.d, text, submit });
+    }
+    async swipe(direction, from, distance) {
+        if (!this.size)
+            this.size = await this.drv.call('size', this.d);
+        const s = this.size;
+        const start = from ?? { x: s.width / 2, y: s.height / 2 };
+        const dist = distance ?? Math.round((direction === 'up' || direction === 'down' ? s.height : s.width) * 0.4);
+        const [dx, dy] = { up: [0, -1], down: [0, 1], left: [-1, 0], right: [1, 0] }[direction];
+        const clamp = (v, hi) => Math.max(1, Math.min(hi - 1, Math.round(v)));
+        await this.drv.call('swipe', { ...this.d, x1: clamp(start.x, s.width), y1: clamp(start.y, s.height),
+            x2: clamp(start.x + dx * dist, s.width), y2: clamp(start.y + dy * dist, s.height), ms: 400 });
+    }
+    async key(key) {
+        const k = KEYS[key];
+        if (!k || (this.platform === 'ios' && (key === 'back' || key === 'recents')))
+            throw new MobiusError('UNSUPPORTED_CAPABILITY', `Key "${key}" is not available on this device`);
+        await this.drv.call('key', { ...this.d, key: k });
+    }
+    async openApp(appId) {
+        await this.drv.call('launch', { ...this.d, app: appId }).catch(e => {
+            throw new MobiusError('APP_NOT_INSTALLED', e.message, { hint: 'Call list_apps to see installed apps.' });
+        });
+    }
+    async openUrl(url) { await this.drv.call('url', { ...this.d, url }); }
+    async listApps() { return (await this.drv.call('apps', this.d)).apps; }
+    async extra(op, args = {}) {
+        // Long-running ops get their own budget: sessions (`seconds`), routes, installs, first OCR build.
+        const secs = Number(args.seconds ?? 0);
+        const timeout = op === 'gps_route' ? 3_700_000 : op === 'install' ? 300_000
+            : ['perf_report', 'watch_crashes'].includes(op) ? (secs + 120) * 1000 : ['ocr', 'bug_report', 'replay'].includes(op) ? 180_000 : 60_000;
+        return this.drv.call(op, { ...this.d, ...args }, timeout);
+    }
+}

package/dist/execution/drivers/nodes.d.ts

@@ -0,0 +1,47 @@
+import type { Framework } from '../../core/protocol.ts';
+import type { RawNode } from '../connector.ts';
+/** A node as drivers report it: Android (uiautomator / on-device helper) or iOS (XCUITest snapshot). */
+export interface SnapshotNode {
+    class?: string;
+    text?: string;
+    hint?: string;
+    'content-desc'?: string;
+    'resource-id'?: string;
+    focused?: boolean;
+    enabled?: boolean;
+    checked?: boolean;
+    checkable?: boolean;
+    clickable?: boolean;
+    selected?: boolean;
+    visible?: boolean;
+    editable?: boolean;
+    /** The platform password flag, when the driver reports it. */
+    password?: boolean;
+    rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    children?: SnapshotNode[] | null;
+    type?: string;
+    label?: string;
+    name?: string;
+    value?: string | null;
+    title?: string;
+    elementType?: number;
+    identifier?: string;
+    hasFocus?: boolean;
+    placeholderValue?: string;
+    frame?: {
+        X: number;
+        Y: number;
+        Width: number;
+        Height: number;
+    };
+}
+export declare function toRawNode(n: SnapshotNode, path: string): RawNode | null;
+/** Flutter / React Native detection from the APK's native libs, via adb (Android only). */
+export declare function detectAndroidFramework(serial: string, pkg: string): Promise<Framework>;
+/** Flutter / React Native detection from a simulator app bundle's embedded frameworks. */
+export declare function detectIosSimFramework(udid: string, bundleId: string): Promise<Framework>;

package/dist/execution/drivers/nodes.js

@@ -0,0 +1,104 @@
+// Execution: normalizing what device drivers report into Mobius's RawNode tree, and detecting an app's UI framework.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+// XCUIElement.ElementType codes we care about → Android-ish class names the normalizer understands.
+const IOS_TYPES = {
+    7: 'Alert', 9: 'Button', 10: 'RadioButton', 12: 'CheckBox', 14: 'PopUpButton', 17: 'ToolbarButton', 19: 'Keyboard',
+    20: 'Button(Key)', 21: 'NavigationBar', 22: 'TabBar', 25: 'StatusBar', 26: 'Table(ScrollView)', 32: 'CollectionView',
+    33: 'Slider', 40: 'Switch', 41: 'Switch(Toggle)', 42: 'Button(Link)', 43: 'Image', 45: 'TextField(Search)',
+    46: 'ScrollView', 48: 'StaticText', 49: 'TextField', 50: 'SecureTextField', 52: 'TextField(TextView)', 75: 'Cell', 80: 'Tab',
+};
+const IOS_TAPPABLE = new Set([9, 10, 12, 14, 17, 20, 40, 41, 42, 45, 49, 50, 52, 75, 80]);
+function iosToRawNode(n, path) {
+    const t = n.elementType ?? 0;
+    if (t === 25)
+        return null; // status bar
+    const f = n.frame ?? { X: 0, Y: 0, Width: 0, Height: 0 };
+    const cls = IOS_TYPES[t] ?? 'Other';
+    const editable = t === 45 || t === 49 || t === 50 || t === 52;
+    const value = typeof n.value === 'string' ? n.value : '';
+    const label = n.label || n.title || '';
+    const node = {
+        cls, pkg: '',
+        text: editable || t === 48 ? value || (t === 48 ? label : '') : '',
+        desc: t === 48 ? (value && value !== label ? label : '') : label || (editable ? n.placeholderValue ?? '' : ''),
+        resourceId: n.identifier ?? '',
+        clickable: IOS_TAPPABLE.has(t),
+        longClickable: false,
+        enabled: n.enabled !== false,
+        focused: !!n.hasFocus,
+        scrollable: t === 26 || t === 32 || t === 46,
+        checkable: t === 12 || t === 40 || t === 41,
+        checked: (t === 40 || t === 41 || t === 12) && (value === '1' || value === 'on'),
+        selected: !!n.selected,
+        password: t === 50 || (editable && SECRET_FIELD.test(`${label} ${n.placeholderValue ?? ''} ${n.identifier ?? ''}`)),
+        bounds: { x: f.X, y: f.Y, width: f.Width, height: f.Height },
+        path,
+        children: [],
+    };
+    (n.children ?? []).forEach((c, i) => { const ch = iosToRawNode(c, `${path}.${i}`); if (ch)
+        node.children.push(ch); });
+    return node;
+}
+// Status bar holds notification previews (message text, OTP senders): never shown to the agent.
+const HIDDEN_IDS = /^com\.android\.systemui:id\/(status_bar_container|status_bar_launch_animation_container)$/;
+// Secret fields: the driver's password flag when it has one, plus hint/label/id patterns as a backstop.
+const SECRET_FIELD = /\b(password|passcode|passwd|pin|mpin|upi pin|otp|cvv|cvc|secret)\b|one[- ]?time/i;
+export function toRawNode(n, path) {
+    if (n.elementType !== undefined)
+        return iosToRawNode(n, path);
+    const resourceId = n['resource-id'] ?? '';
+    if (HIDDEN_IDS.test(resourceId))
+        return null;
+    const cls = n.class ?? n.type ?? '';
+    const editable = n.editable ?? /TextField|EditText|SecureTextField/.test(cls);
+    const hint = n.hint ?? '';
+    const desc = n['content-desc'] ?? n.label ?? '';
+    const node = {
+        cls: editable && !/EditText|TextField/.test(cls) ? `${cls}(EditText)` : cls,
+        pkg: '',
+        text: n.text ?? n.value ?? '',
+        desc: desc || (editable ? hint : ''),
+        resourceId: resourceId || n.name || '',
+        clickable: !!n.clickable,
+        longClickable: false,
+        enabled: n.enabled !== false,
+        focused: !!n.focused,
+        scrollable: /RecyclerView|ScrollView|ListView|GridView|ViewPager|ScrollView|Table|CollectionView/.test(cls),
+        checkable: !!n.checkable,
+        checked: !!n.checked,
+        selected: !!n.selected,
+        password: n.password === true || /SecureTextField/.test(cls) || (editable && SECRET_FIELD.test(`${hint} ${desc} ${resourceId}`)),
+        bounds: n.visible === false ? { x: 0, y: 0, width: 0, height: 0 } : (n.rect ?? { x: 0, y: 0, width: 0, height: 0 }),
+        path,
+        children: [],
+    };
+    (n.children ?? []).forEach((c, i) => {
+        const child = toRawNode(c, `${path}.${i}`);
+        if (child)
+            node.children.push(child);
+    });
+    return node;
+}
+/** Flutter / React Native detection from the APK's native libs, via adb (Android only). */
+export async function detectAndroidFramework(serial, pkg) {
+    if (!/^[\w.]+$/.test(pkg))
+        return 'unknown';
+    const sh = async (cmd) => (await run('adb', ['-s', serial, 'shell', cmd], { timeout: 10_000 })).stdout;
+    const apks = (await sh(`pm path ${pkg}`)).split('\n').map(l => l.replace('package:', '').trim()).filter(Boolean);
+    if (!apks.length)
+        return 'unknown';
+    const libs = await sh(`for a in ${apks.map(a => `'${a}'`).join(' ')}; do unzip -l "$a" 2>/dev/null; done | grep -oE "lib(flutter|reactnativejni|hermes)\\.so" | sort -u`);
+    return libs.includes('libflutter') ? 'flutter' : /reactnativejni|hermes/.test(libs) ? 'react_native' : 'native';
+}
+/** Flutter / React Native detection from a simulator app bundle's embedded frameworks. */
+export async function detectIosSimFramework(udid, bundleId) {
+    if (!/^[\w.\-]+$/.test(bundleId) || !/^[\w\-]+$/.test(udid))
+        return 'unknown';
+    const dir = (await run('xcrun', ['simctl', 'get_app_container', udid, bundleId, 'app'], { timeout: 10_000 })).stdout.trim();
+    const { readdir } = await import('node:fs/promises');
+    const fws = await readdir(`${dir}/Frameworks`).catch(() => []);
+    return fws.includes('Flutter.framework') ? 'flutter'
+        : fws.some(f => /React|hermes/i.test(f)) ? 'react_native' : 'native';
+}

package/dist/execution/observe.d.ts

@@ -0,0 +1,48 @@
+import type { Element, Framework, Observation } from '../core/protocol.ts';
+import { type RawScreen } from './connector.ts';
+type Role = Element['role'];
+export declare function scrub(s: string): string;
+export interface Fingerprint {
+    role: Role;
+    text: string | null;
+    label: string | null;
+    resource_id: string | null;
+    cls: string;
+    path: string;
+    dup_index: number;
+}
+export interface Normalized {
+    elements: Element[];
+    fingerprints: Map<string, Fingerprint>;
+    screen_hash: string;
+    tree_quality: Observation['tree_quality'];
+    keyboard: Observation['keyboard'];
+}
+export declare const MAX_ELEMENTS = 400;
+export declare function normalize(screen: RawScreen, obsId: string): Normalized & {
+    truncated: boolean;
+};
+/** Per-device observation history. Element ids are only honoured against the latest screen.
+ *  With `persistAs` (the real CLI), recent identities and the id counter survive a restart, so an id an agent got from
+ *  an earlier Mobius process still resolves against the live screen (same identity rules, same ambiguity checks). */
+export declare class ObservationStore {
+    private seq;
+    private history;
+    private saved;
+    private readonly file;
+    constructor(persistAs?: string);
+    nextId(): string;
+    add(obs: Observation, fps: Map<string, Fingerprint>): void;
+    latest(): Observation | null;
+    /**
+     * Resolve an element id to an element on the latest screen.
+     * Same observation → direct. Older observation → re-find by identity (role/text/label/resource_id/dup_index);
+     * unique match survives benign re-renders, otherwise STALE_ELEMENT / AMBIGUOUS_TARGET.
+     */
+    resolve(id: string): Element;
+}
+export declare function buildObservation(screen: RawScreen, deviceId: string, platform: Observation['platform'], obsId: string, framework: Framework): {
+    obs: Observation;
+    fps: Map<string, Fingerprint>;
+};
+export {};

package/dist/execution/observe.js

@@ -0,0 +1,246 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { mobiusHome } from "../observability/audit.js";
+import { createHash } from 'node:crypto';
+import { MobiusError } from "./connector.js";
+function roleOf(n) {
+    const c = n.cls;
+    if (/EditText|TextField|AutoCompleteTextView/.test(c))
+        return 'textbox';
+    if (/Switch/.test(c))
+        return 'switch';
+    if (/CheckBox/.test(c))
+        return 'checkbox';
+    if (/RadioButton/.test(c))
+        return 'radio';
+    if (/Button/.test(c))
+        return 'button';
+    if (/RecyclerView|ListView|ScrollView|GridView|ViewPager/.test(c))
+        return 'list';
+    if (/Tab/.test(c))
+        return 'tab';
+    if (n.checkable)
+        return 'checkbox';
+    if (n.clickable || n.longClickable)
+        return 'button';
+    if (/ImageView|Image/.test(c))
+        return 'image';
+    if (n.text)
+        return 'text';
+    return 'view';
+}
+// ponytail: pattern-based redaction (password flag, card-like digit runs, OTP/verification codes).
+// Applied to text AND labels (Flutter merges row text into labels). Per-app rules come with the policy engine.
+const REDACTED = '[redacted]';
+const CARD_LIKE = /\b(?:\d[ -]?){12,18}\d\b/g;
+// Digits may be spaced or dashed ("4 8 2 9 1 3", "482-913") to dodge a plain \d{6} match.
+const OTP_LIKE = /\b(otp|one[- ]?time|verification code|security code|passcode|pin|cvv|cvc)\b([^\d]{0,25})\d(?:[ -]?\d){2,7}\b/gi;
+export function scrub(s) {
+    return s.replace(CARD_LIKE, REDACTED).replace(OTP_LIKE, (_m, kw, mid) => `${kw}${mid}${REDACTED}`);
+}
+/** A field asking for a secret, whatever the driver reported (an app may not set the password flag on a PIN box). */
+const SECRET_FIELD = /\b(password|passcode|passwd|pin|mpin|upi pin|otp|cvv|cvc|secret)\b|one[- ]?time/i;
+const isSensitive = (n) => n.password || scrub(n.text) !== n.text || scrub(n.desc) !== n.desc
+    || (roleOf(n) === 'textbox' && SECRET_FIELD.test(`${n.desc} ${n.resourceId}`));
+const visible = (n) => n.bounds.width > 0 && n.bounds.height > 0;
+const interactive = (n) => n.clickable || n.longClickable || n.scrollable || n.checkable || roleOf(n) === 'textbox';
+/** Text of non-interactive descendants, for labelling a clickable container that has none itself. */
+function descendantText(n, out = []) {
+    for (const c of n.children) {
+        if (out.length >= 3)
+            break;
+        if (interactive(c))
+            continue;
+        const t = c.text || c.desc;
+        if (t && !c.password)
+            out.push(scrub(t));
+        descendantText(c, out);
+    }
+    return out;
+}
+// Soft keyboards: iOS Keyboard element, or Android IME packages (Gboard, Samsung, SwiftKey...).
+const isKeyboard = (n) => n.cls === 'Keyboard' || /inputmethod|keyboard|honeyboard|swiftkey/i.test(n.resourceId.split(':')[0] ?? '');
+export const MAX_ELEMENTS = 400;
+export function normalize(screen, obsId) {
+    const picked = [];
+    let kb = null;
+    const walk = (n, insideClickable) => {
+        if (isKeyboard(n) && visible(n)) {
+            const b = n.bounds;
+            kb = kb ? { x1: Math.min(kb.x1, b.x), y1: Math.min(kb.y1, b.y), x2: Math.max(kb.x2, b.x + b.width), y2: Math.max(kb.y2, b.y + b.height) }
+                : { x1: b.x, y1: b.y, x2: b.x + b.width, y2: b.y + b.height };
+            return; // keys are noise for the agent; the area is reported as `keyboard`
+        }
+        if (!visible(n) && n.cls !== 'hierarchy') {
+            // Zero-size containers (common on iOS) can still hold visible children.
+            for (const c of n.children)
+                walk(c, insideClickable);
+            return;
+        }
+        const own = n.text || n.desc;
+        const isInteractive = interactive(n);
+        if (isInteractive) {
+            let text = n.text ? (n.password ? REDACTED : scrub(n.text)) : null;
+            const label = n.desc ? scrub(n.desc) : null;
+            if (!text && !label && (n.clickable || n.longClickable))
+                text = descendantText(n).join(' · ') || null;
+            picked.push({ n, text, label });
+        }
+        else if (own && !insideClickable) {
+            // Plain text not owned by a clickable ancestor stays readable for the agent.
+            picked.push({ n, text: n.text ? (n.password ? REDACTED : scrub(n.text)) : null, label: n.desc ? scrub(n.desc) : null });
+        }
+        const clickableHere = insideClickable || n.clickable || n.longClickable;
+        for (const c of n.children)
+            walk(c, clickableHere);
+    };
+    if (screen.root)
+        walk(screen.root, false);
+    const truncated = picked.length > MAX_ELEMENTS;
+    const dupCount = new Map();
+    const fingerprints = new Map();
+    const elements = picked.slice(0, MAX_ELEMENTS).map(({ n, text, label }, i) => {
+        const role = roleOf(n);
+        const key = `${role}|${text}|${label}`;
+        const dup_index = text || label ? dupCount.get(key) ?? 0 : 0; // unlabeled nodes aren't "duplicates"
+        if (text || label)
+            dupCount.set(key, dup_index + 1);
+        const id = `${obsId}:e${i + 1}`;
+        const resource_id = n.resourceId || null;
+        fingerprints.set(id, { role, text, label, resource_id, cls: n.cls, path: n.path, dup_index });
+        return {
+            id, role, text, label, resource_id,
+            clickable: n.clickable, long_clickable: n.longClickable, enabled: n.enabled, focused: n.focused,
+            scrollable: n.scrollable, editable: role === 'textbox', checked: n.checkable ? n.checked : null,
+            selected: n.selected, sensitive: isSensitive(n), bounds: n.bounds, dup_index,
+        };
+    });
+    const screen_hash = createHash('sha1')
+        .update(JSON.stringify(elements.map(e => [e.role, e.text, e.label, e.resource_id, e.bounds, e.enabled, e.checked])))
+        .digest('hex').slice(0, 12);
+    const actionable = elements.filter(e => e.clickable || e.editable || e.long_clickable);
+    const unlabeled = actionable.filter(e => !e.text && !e.label && !e.resource_id).length;
+    const tree_quality = elements.length === 0 ? 'empty'
+        : actionable.length <= 1 || unlabeled / Math.max(actionable.length, 1) > 0.5 ? 'sparse'
+            : 'good';
+    const k = kb;
+    const keyboard = k ? { x: k.x1, y: k.y1, width: k.x2 - k.x1, height: k.y2 - k.y1 } : null;
+    return { elements, fingerprints, screen_hash, tree_quality, truncated, keyboard };
+}
+const sameIdentity = (a, e) => a.role === e.role && a.text === e.text && a.label === e.label && a.resource_id === e.resource_id;
+/** Identity of an element as a hash: what gets saved to disk, so no screen text is ever written there. */
+const identityHash = (f) => createHash('sha256').update(JSON.stringify([f.role, f.text, f.label, f.resource_id])).digest('base64url').slice(0, 22);
+/** Per-device observation history. Element ids are only honoured against the latest screen.
+ *  With `persistAs` (the real CLI), recent identities and the id counter survive a restart, so an id an agent got from
+ *  an earlier Mobius process still resolves against the live screen (same identity rules, same ambiguity checks). */
+export class ObservationStore {
+    seq = 0;
+    history = [];
+    saved = [];
+    file;
+    constructor(persistAs) {
+        this.file = persistAs ? join(mobiusHome(), 'obs', `${persistAs.replace(/[^\w.-]/g, '_')}.json`) : null;
+        if (!this.file)
+            return;
+        try {
+            const d = JSON.parse(readFileSync(this.file, 'utf8'));
+            this.seq = d.seq | 0;
+            this.saved = Array.isArray(d.saved) ? d.saved.slice(-5) : [];
+        }
+        catch { /* first run on this device */ }
+    }
+    nextId() { return `o${++this.seq}`; }
+    add(obs, fps) {
+        this.history.push({ obs, fps });
+        // ponytail: settle/verify polls add an observation every ~100 ms, so a small window evicts the ids the agent
+        // just got from observe after one slow action. 64 covers a full verify timeout; the on-disk copy stays at 5.
+        if (this.history.length > 64)
+            this.history.shift();
+        if (!this.file)
+            return;
+        this.saved.push([...fps].map(([id, f]) => ({ id, hash: identityHash(f), dup: f.dup_index, rid: !!f.resource_id })));
+        this.saved = this.saved.slice(-5);
+        try {
+            mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 });
+            writeFileSync(this.file, JSON.stringify({ seq: this.seq, saved: this.saved }), { mode: 0o600 });
+        }
+        catch { /* best effort: ids still work within this process */ }
+    }
+    latest() { return this.history.at(-1)?.obs ?? null; }
+    /**
+     * Resolve an element id to an element on the latest screen.
+     * Same observation → direct. Older observation → re-find by identity (role/text/label/resource_id/dup_index);
+     * unique match survives benign re-renders, otherwise STALE_ELEMENT / AMBIGUOUS_TARGET.
+     */
+    resolve(id) {
+        const latest = this.history.at(-1);
+        if (!latest)
+            throw new MobiusError('STALE_ELEMENT', `No observation yet for ${id}`, { retryable: true, hint: 'Call observe first.' });
+        const direct = latest.obs.elements.find(e => e.id === id);
+        if (direct)
+            return direct;
+        const fp = this.history.find(h => h.fps.has(id))?.fps.get(id);
+        if (!fp) {
+            // An id from an earlier process: match by saved identity hash on the live screen.
+            const sv = this.saved.flat().find(x => x.id === id);
+            if (sv) {
+                const m = latest.obs.elements.filter(e => identityHash(e) === sv.hash);
+                const { width: W, height: H } = latest.obs.screen;
+                const vis = m.filter(e => e.bounds.y + e.bounds.height > 0 && e.bounds.y < H && e.bounds.x + e.bounds.width > 0 && e.bounds.x < W);
+                if (m.length === 1)
+                    return m[0];
+                if (vis.length === 1)
+                    return vis[0];
+                const exact = m.filter(e => e.dup_index === sv.dup);
+                if (m.length > 1 && exact.length === 1 && sv.rid)
+                    return exact[0];
+                if (m.length > 1)
+                    throw new MobiusError('AMBIGUOUS_TARGET', `${id} matches ${m.length} elements on the current screen`, { hint: `Pick one of: ${m.map(e => e.id).join(', ')}` });
+                throw new MobiusError('STALE_ELEMENT', `${id} is not on the current screen (${latest.obs.observation_id})`, { retryable: true, hint: 'The screen changed. Call observe and pick a fresh id.' });
+            }
+            throw new MobiusError('ELEMENT_NOT_FOUND', `Unknown element id ${id}`, {
+                hint: `Use an id from the latest observation (${latest.obs.observation_id}).`,
+            });
+        }
+        const matches = latest.obs.elements.filter(e => sameIdentity(fp, e));
+        const exact = matches.filter(e => e.dup_index === fp.dup_index);
+        if (matches.length === 1)
+            return matches[0];
+        // A copy scrolled far off-screen (sticky headers leave one in the tree; Slikk, live run) isn't what the agent means.
+        const { width: W, height: H } = latest.obs.screen;
+        const visible = matches.filter(e => e.bounds.y + e.bounds.height > 0 && e.bounds.y < H && e.bounds.x + e.bounds.width > 0 && e.bounds.x < W);
+        if (visible.length === 1)
+            return visible[0];
+        if (exact.length === 1 && matches.length > 1 && fp.resource_id)
+            return exact[0];
+        if (matches.length > 1) {
+            throw new MobiusError('AMBIGUOUS_TARGET', `${id} matches ${matches.length} elements on the current screen`, {
+                hint: `Pick one of: ${matches.map(m => m.id).join(', ')}`,
+            });
+        }
+        throw new MobiusError('STALE_ELEMENT', `${id} is not on the current screen (${latest.obs.observation_id})`, {
+            retryable: true, hint: 'The screen changed. Call observe and pick a fresh id.',
+        });
+    }
+}
+export function buildObservation(screen, deviceId, platform, obsId, framework) {
+    const n = normalize(screen, obsId);
+    return {
+        obs: {
+            observation_id: obsId,
+            device_id: deviceId,
+            platform,
+            foreground_app: screen.foregroundApp,
+            screen: { width: screen.width, height: screen.height, rotation: screen.rotation },
+            screen_hash: n.screen_hash,
+            framework,
+            tree_quality: n.tree_quality,
+            sources: ['a11y'],
+            elements: n.elements,
+            untrusted_content: true,
+            truncated: n.truncated,
+            keyboard: n.keyboard,
+        },
+        fps: n.fingerprints,
+    };
+}