@anuraghq/mobius 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { AuditLog } from "./observability/audit.js";
+import { createServer } from "./interface/mcp.js";
+import { createEngine } from "./interface/engine.js";
+import { createHttpServer } from "./interface/http.js";
+import { randomBytes } from 'node:crypto';
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { issueSession, rotateInstallKey, verifySession } from "./observability/signing.js";
+/** Session tokens are verified with this install's key, or an operator key (MOBIUS_SESSION_PUBKEY = path to a PEM). */
+const operatorKey = process.env.MOBIUS_SESSION_PUBKEY ? readFileSync(process.env.MOBIUS_SESSION_PUBKEY, 'utf8') : undefined;
+import { driverBuilt, driverPath, iosAgentReady, MobiusAgentConnector, MobiusAgentDriver } from "./execution/drivers/mobiusagent.js";
+/** Every online device through the Mobius driver. iOS devices also need the Mobius Agent runner set up once. */
+const connectors = (driver) => async () => {
+    if (!driverBuilt())
+        throw new Error(`Mobius driver not built: run \`cargo build --release\` in drivers/mobiusagent-driver (expected ${driverPath()})`);
+    const ios = iosAgentReady();
+    return (await driver.devices()).filter(d => d.state === 'online' && (d.platform === 'android' || ios)).map(d => new MobiusAgentConnector(driver, d));
+};
+import { defaultApprover, Policy } from "./policy/policy.js";
+import { writeFileSync, rmSync } from 'node:fs';
+import { killSwitchPath, revokedPath } from "./infrastructure/plane.js";
+import { mobiusHome } from "./observability/audit.js";
+import { Mobius } from "./infrastructure/registry.js";
+const log = (level, msg, extra = {}) => process.stderr.write(JSON.stringify({ ts: new Date().toISOString(), level, msg, ...extra }) + '\n'); // stdout is the MCP channel
+const cmd = process.argv[2] ?? 'mcp';
+if (cmd === 'mcp') {
+    // ponytail: stdio server owns devices directly. The shared daemon + bridge from DESIGN.md arrives
+    // with the Android app connector, when a long-lived WebSocket owner is actually needed.
+    const driver = new MobiusAgentDriver();
+    const audit = new AuditLog();
+    const mobius = new Mobius(connectors(driver), audit, new Policy(), defaultApprover());
+    mobius.persistIds = true;
+    // A signed agent session handed to this MCP server by its operator (identity + policy version for every action).
+    const tok = process.env.MOBIUS_SESSION_TOKEN;
+    if (tok) {
+        const check = () => verifySession(tok, operatorKey ?? audit.signer.publicKeyPem);
+        const v = check();
+        // Re-verified on every action: a key rotation or expiry takes effect mid-session (revocation is checked in the gate).
+        mobius.plane.session = () => { const r = check(); return r.ok ? r.claims : { invalid: r.reason }; };
+        log(v.ok ? 'info' : 'error', v.ok ? 'agent session verified' : 'agent session token rejected', v.ok ? { agent: v.claims.sub, policy: v.claims.policy_version ?? null } : { reason: v.reason });
+    }
+    const server = createServer(mobius);
+    await server.connect(new StdioServerTransport());
+    log('info', 'mobius mcp ready');
+    const shutdown = async () => { driver.close(); process.exit(0); };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    process.stdin.on('close', shutdown);
+}
+else if (cmd === 'serve') {
+    // REST front door (same engine as MCP). Local by default; put it behind your own TLS proxy to expose it.
+    const args = process.argv.slice(3);
+    const opt = (k, d) => { const i = args.indexOf(`--${k}`); return i >= 0 && args[i + 1] ? args[i + 1] : d; };
+    const port = Number(opt('port', '7777')), host = opt('host', '127.0.0.1');
+    let token = process.env.MOBIUS_API_TOKEN ?? '';
+    if (!token) {
+        token = randomBytes(24).toString('base64url');
+        process.stderr.write(`MOBIUS_API_TOKEN not set; generated one for this run:\n  ${token}\n`);
+    }
+    const driver = new MobiusAgentDriver();
+    const audit = new AuditLog();
+    const mobius = new Mobius(connectors(driver), audit, new Policy(), defaultApprover());
+    mobius.persistIds = true;
+    const engine = await createEngine(mobius);
+    createHttpServer(engine, audit, token, operatorKey).listen(port, host, () => log('info', 'mobius rest ready', { url: `http://${host}:${port}/v1` }));
+    const shutdown = async () => { await engine.close().catch(() => { }); driver.close(); process.exit(0); };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+else if (cmd === 'keys' && process.argv[3] === 'rotate') {
+    // Retire the install key (its public half is kept so old audit entries still verify) and start a new one.
+    rotateInstallKey(mobiusHome());
+    process.stdout.write('Key rotated. Running Mobius servers switch to the new key on their next action.\nEvery session token signed by the old key is now refused: issue new ones with `mobius session issue`.\n');
+}
+else if (cmd === 'keys') {
+    // The public half of this install's key: verifies its audit logs and the session tokens it issues.
+    // --all: every key it has used, oldest first, as JSON (what an auditor needs to verify a log across rotations).
+    const a = new AuditLog();
+    process.stdout.write(process.argv[3] === '--all' ? JSON.stringify(a.keyring(), null, 2) + '\n' : a.signer.publicKeyPem);
+}
+else if (cmd === 'session' && process.argv[3] === 'revoke') {
+    // mobius session revoke <jti>: the jti is printed at issue time and recorded on every audit entry.
+    const jti = process.argv[4];
+    if (!jti || !/^[\w.-]{1,128}$/.test(jti)) {
+        process.stderr.write('usage: mobius session revoke <session id (jti), e.g. ses_1a2b3c>\n');
+        process.exit(2);
+    }
+    appendFileSync(revokedPath(), jti + '\n', { mode: 0o600 });
+    process.stdout.write(`Session ${jti} revoked: every Mobius on this machine refuses its actions from now on.\n`);
+}
+else if (cmd === 'session' && process.argv[3] === 'issue') {
+    // mobius session issue --agent acme-bot/1.0 [--ttl 8h] [--policy-version v3] [--issuer ops-team]
+    const args = process.argv.slice(4);
+    const opt = (k) => { const i = args.indexOf(`--${k}`); return i >= 0 ? args[i + 1] : undefined; };
+    const agent = opt('agent');
+    if (!agent) {
+        process.stderr.write('usage: mobius session issue --agent <name/version> [--ttl 8h] [--policy-version <v>] [--issuer <who>]\n');
+        process.exit(2);
+    }
+    const m = /^(\d+)(m|h|d)$/.exec(opt('ttl') ?? '8h');
+    if (!m) {
+        process.stderr.write('--ttl: e.g. 30m, 8h, 7d\n');
+        process.exit(2);
+    }
+    const now = Math.floor(Date.now() / 1000);
+    const pv = opt('policy-version'), iss = opt('issuer');
+    const jti = `ses_${randomBytes(6).toString('hex')}`;
+    process.stderr.write(`session id ${jti} (revoke with: mobius session revoke ${jti})\n`);
+    process.stdout.write(issueSession(new AuditLog().signer, {
+        sub: agent, jti, iat: now, exp: now + Number(m[1]) * { m: 60, h: 3600, d: 86400 }[m[2]],
+        ...(pv ? { policy_version: pv } : {}), ...(iss ? { iss } : {}),
+    }) + '\n');
+}
+else if (cmd === 'setup-ios') {
+    // One-time iOS setup: build, patch, sign and install the Mobius Agent runner with your Apple developer team.
+    const { spawnSync } = await import('node:child_process');
+    const { fileURLToPath } = await import('node:url');
+    const script = [new URL('../ios-agent/setup.sh', import.meta.url), new URL('../../../drivers/mobiusagent-driver/ios-agent/setup.sh', import.meta.url)]
+        .map(u => fileURLToPath(u)).find(p => existsSync(p));
+    if (!script) {
+        process.stderr.write('ios-agent/setup.sh not found in this install\n');
+        process.exit(1);
+    }
+    if (!process.env.MOBIUS_TEAM_ID) {
+        process.stderr.write('Set MOBIUS_TEAM_ID to your Apple developer team id (the OU of your "Apple Development" certificate):\n  MOBIUS_TEAM_ID=XXXXXXXXXX mobius setup-ios\n');
+        process.exit(2);
+    }
+    process.exit(spawnSync('sh', [script], { stdio: 'inherit' }).status ?? 1);
+}
+else if (cmd === 'stop') {
+    // Kill switch: every running Mobius refuses state-changing actions until `mobius resume`.
+    writeFileSync(killSwitchPath(), new Date().toISOString());
+    process.stdout.write('Kill switch engaged: all agent actions are stopped. Run `mobius resume` to allow them again.\n');
+}
+else if (cmd === 'resume') {
+    rmSync(killSwitchPath(), { force: true });
+    process.stdout.write('Kill switch released.\n');
+}
+else if (cmd === 'audit' && process.argv[3] === 'export') {
+    process.stdout.write(new AuditLog().exportJsonl() + '\n');
+}
+else if (cmd === 'audit' && process.argv[3] === 'verify') {
+    const r = new AuditLog().verify();
+    process.stdout.write(r.ok ? `Audit log intact: ${r.rows} entries, chain and signatures verified${r.legacy_unsigned ? ` (${r.legacy_unsigned} older unsigned entries)` : ''}.\n` : `TAMPERED at ${r.broken_at}: ${r.reason} (${r.rows} entries).\n`);
+    process.exit(r.ok ? 0 : 1);
+}
+else {
+    process.stderr.write('usage: mobius mcp | serve [--port 7777] [--host 127.0.0.1] | session issue --agent <name> | session revoke <jti> | keys [--all] | keys rotate | setup-ios | stop | resume | audit export | audit verify\n');
+    process.exit(2);
+}

package/dist/core/protocol.d.ts

@@ -0,0 +1,294 @@
+import { z } from 'zod';
+export declare const PROTOCOL_VERSION = 1;
+export declare const ErrorCode: z.ZodEnum<{
+    INVALID_INPUT: "INVALID_INPUT";
+    DEVICE_NOT_FOUND: "DEVICE_NOT_FOUND";
+    DEVICE_OFFLINE: "DEVICE_OFFLINE";
+    DEVICE_LOCKED: "DEVICE_LOCKED";
+    SERVICE_DISABLED: "SERVICE_DISABLED";
+    PERMISSION_REQUIRED: "PERMISSION_REQUIRED";
+    UNSUPPORTED_CAPABILITY: "UNSUPPORTED_CAPABILITY";
+    ELEMENT_NOT_FOUND: "ELEMENT_NOT_FOUND";
+    AMBIGUOUS_TARGET: "AMBIGUOUS_TARGET";
+    STALE_ELEMENT: "STALE_ELEMENT";
+    SECURE_WINDOW: "SECURE_WINDOW";
+    APP_NOT_INSTALLED: "APP_NOT_INSTALLED";
+    POLICY_BLOCKED: "POLICY_BLOCKED";
+    APPROVAL_REQUIRED: "APPROVAL_REQUIRED";
+    APPROVAL_REJECTED: "APPROVAL_REJECTED";
+    APPROVAL_EXPIRED: "APPROVAL_EXPIRED";
+    BUDGET_EXCEEDED: "BUDGET_EXCEEDED";
+    LOOP_DETECTED: "LOOP_DETECTED";
+    RATE_LIMITED: "RATE_LIMITED";
+    DUPLICATE_ACTION: "DUPLICATE_ACTION";
+    TIMEOUT: "TIMEOUT";
+    CANCELLED: "CANCELLED";
+    OUTCOME_UNKNOWN: "OUTCOME_UNKNOWN";
+    FOREGROUND_REQUIRED: "FOREGROUND_REQUIRED";
+    INTERNAL: "INTERNAL";
+}>;
+export type ErrorCode = z.infer<typeof ErrorCode>;
+export declare const Platform: z.ZodEnum<{
+    android: "android";
+    ios: "ios";
+}>;
+export declare const Framework: z.ZodEnum<{
+    native: "native";
+    flutter: "flutter";
+    react_native: "react_native";
+    unknown: "unknown";
+}>;
+export type Framework = z.infer<typeof Framework>;
+export declare const TreeQuality: z.ZodEnum<{
+    good: "good";
+    sparse: "sparse";
+    empty: "empty";
+}>;
+export declare const Bounds: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+export type Bounds = z.infer<typeof Bounds>;
+export declare const Role: z.ZodEnum<{
+    button: "button";
+    textbox: "textbox";
+    checkbox: "checkbox";
+    switch: "switch";
+    radio: "radio";
+    image: "image";
+    text: "text";
+    list: "list";
+    tab: "tab";
+    view: "view";
+}>;
+export declare const Element: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodEnum<{
+        button: "button";
+        textbox: "textbox";
+        checkbox: "checkbox";
+        switch: "switch";
+        radio: "radio";
+        image: "image";
+        text: "text";
+        list: "list";
+        tab: "tab";
+        view: "view";
+    }>;
+    text: z.ZodNullable<z.ZodString>;
+    label: z.ZodNullable<z.ZodString>;
+    resource_id: z.ZodNullable<z.ZodString>;
+    clickable: z.ZodBoolean;
+    long_clickable: z.ZodBoolean;
+    enabled: z.ZodBoolean;
+    focused: z.ZodBoolean;
+    scrollable: z.ZodBoolean;
+    editable: z.ZodBoolean;
+    checked: z.ZodNullable<z.ZodBoolean>;
+    selected: z.ZodBoolean;
+    sensitive: z.ZodBoolean;
+    bounds: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+    dup_index: z.ZodNumber;
+}, z.core.$strip>;
+export type Element = z.infer<typeof Element>;
+export declare const Observation: z.ZodObject<{
+    observation_id: z.ZodString;
+    device_id: z.ZodString;
+    platform: z.ZodEnum<{
+        android: "android";
+        ios: "ios";
+    }>;
+    foreground_app: z.ZodNullable<z.ZodString>;
+    screen: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        rotation: z.ZodNumber;
+    }, z.core.$strip>;
+    screen_hash: z.ZodString;
+    framework: z.ZodEnum<{
+        native: "native";
+        flutter: "flutter";
+        react_native: "react_native";
+        unknown: "unknown";
+    }>;
+    tree_quality: z.ZodEnum<{
+        good: "good";
+        sparse: "sparse";
+        empty: "empty";
+    }>;
+    sources: z.ZodArray<z.ZodEnum<{
+        a11y: "a11y";
+        flutter_vm: "flutter_vm";
+        vision: "vision";
+    }>>;
+    elements: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodEnum<{
+            button: "button";
+            textbox: "textbox";
+            checkbox: "checkbox";
+            switch: "switch";
+            radio: "radio";
+            image: "image";
+            text: "text";
+            list: "list";
+            tab: "tab";
+            view: "view";
+        }>;
+        text: z.ZodNullable<z.ZodString>;
+        label: z.ZodNullable<z.ZodString>;
+        resource_id: z.ZodNullable<z.ZodString>;
+        clickable: z.ZodBoolean;
+        long_clickable: z.ZodBoolean;
+        enabled: z.ZodBoolean;
+        focused: z.ZodBoolean;
+        scrollable: z.ZodBoolean;
+        editable: z.ZodBoolean;
+        checked: z.ZodNullable<z.ZodBoolean>;
+        selected: z.ZodBoolean;
+        sensitive: z.ZodBoolean;
+        bounds: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>;
+        dup_index: z.ZodNumber;
+    }, z.core.$strip>>;
+    untrusted_content: z.ZodLiteral<true>;
+    truncated: z.ZodBoolean;
+    keyboard: z.ZodNullable<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Observation = z.infer<typeof Observation>;
+export declare const MobiusErrorBody: z.ZodObject<{
+    code: z.ZodEnum<{
+        INVALID_INPUT: "INVALID_INPUT";
+        DEVICE_NOT_FOUND: "DEVICE_NOT_FOUND";
+        DEVICE_OFFLINE: "DEVICE_OFFLINE";
+        DEVICE_LOCKED: "DEVICE_LOCKED";
+        SERVICE_DISABLED: "SERVICE_DISABLED";
+        PERMISSION_REQUIRED: "PERMISSION_REQUIRED";
+        UNSUPPORTED_CAPABILITY: "UNSUPPORTED_CAPABILITY";
+        ELEMENT_NOT_FOUND: "ELEMENT_NOT_FOUND";
+        AMBIGUOUS_TARGET: "AMBIGUOUS_TARGET";
+        STALE_ELEMENT: "STALE_ELEMENT";
+        SECURE_WINDOW: "SECURE_WINDOW";
+        APP_NOT_INSTALLED: "APP_NOT_INSTALLED";
+        POLICY_BLOCKED: "POLICY_BLOCKED";
+        APPROVAL_REQUIRED: "APPROVAL_REQUIRED";
+        APPROVAL_REJECTED: "APPROVAL_REJECTED";
+        APPROVAL_EXPIRED: "APPROVAL_EXPIRED";
+        BUDGET_EXCEEDED: "BUDGET_EXCEEDED";
+        LOOP_DETECTED: "LOOP_DETECTED";
+        RATE_LIMITED: "RATE_LIMITED";
+        DUPLICATE_ACTION: "DUPLICATE_ACTION";
+        TIMEOUT: "TIMEOUT";
+        CANCELLED: "CANCELLED";
+        OUTCOME_UNKNOWN: "OUTCOME_UNKNOWN";
+        FOREGROUND_REQUIRED: "FOREGROUND_REQUIRED";
+        INTERNAL: "INTERNAL";
+    }>;
+    message: z.ZodString;
+    retryable: z.ZodBoolean;
+    hint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const ActionStatus: z.ZodEnum<{
+    succeeded: "succeeded";
+    failed: "failed";
+    blocked: "blocked";
+    pending_approval: "pending_approval";
+    outcome_unknown: "outcome_unknown";
+}>;
+export declare const ActionResult: z.ZodObject<{
+    ok: z.ZodBoolean;
+    action_id: z.ZodString;
+    status: z.ZodEnum<{
+        succeeded: "succeeded";
+        failed: "failed";
+        blocked: "blocked";
+        pending_approval: "pending_approval";
+        outcome_unknown: "outcome_unknown";
+    }>;
+    duration_ms: z.ZodNumber;
+    state_changed: z.ZodNullable<z.ZodBoolean>;
+    foreground_app: z.ZodNullable<z.ZodString>;
+    observation_id: z.ZodNullable<z.ZodString>;
+    verified: z.ZodNullable<z.ZodBoolean>;
+    message: z.ZodString;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodEnum<{
+            INVALID_INPUT: "INVALID_INPUT";
+            DEVICE_NOT_FOUND: "DEVICE_NOT_FOUND";
+            DEVICE_OFFLINE: "DEVICE_OFFLINE";
+            DEVICE_LOCKED: "DEVICE_LOCKED";
+            SERVICE_DISABLED: "SERVICE_DISABLED";
+            PERMISSION_REQUIRED: "PERMISSION_REQUIRED";
+            UNSUPPORTED_CAPABILITY: "UNSUPPORTED_CAPABILITY";
+            ELEMENT_NOT_FOUND: "ELEMENT_NOT_FOUND";
+            AMBIGUOUS_TARGET: "AMBIGUOUS_TARGET";
+            STALE_ELEMENT: "STALE_ELEMENT";
+            SECURE_WINDOW: "SECURE_WINDOW";
+            APP_NOT_INSTALLED: "APP_NOT_INSTALLED";
+            POLICY_BLOCKED: "POLICY_BLOCKED";
+            APPROVAL_REQUIRED: "APPROVAL_REQUIRED";
+            APPROVAL_REJECTED: "APPROVAL_REJECTED";
+            APPROVAL_EXPIRED: "APPROVAL_EXPIRED";
+            BUDGET_EXCEEDED: "BUDGET_EXCEEDED";
+            LOOP_DETECTED: "LOOP_DETECTED";
+            RATE_LIMITED: "RATE_LIMITED";
+            DUPLICATE_ACTION: "DUPLICATE_ACTION";
+            TIMEOUT: "TIMEOUT";
+            CANCELLED: "CANCELLED";
+            OUTCOME_UNKNOWN: "OUTCOME_UNKNOWN";
+            FOREGROUND_REQUIRED: "FOREGROUND_REQUIRED";
+            INTERNAL: "INTERNAL";
+        }>;
+        message: z.ZodString;
+        retryable: z.ZodBoolean;
+        hint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ActionResult = z.infer<typeof ActionResult>;
+/** Post-action expectation; the host waits (state-based) until it holds or times out. */
+export declare const Expect: z.ZodObject<{
+    text_visible: z.ZodOptional<z.ZodString>;
+    app: z.ZodOptional<z.ZodString>;
+    element_gone: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type Expect = z.infer<typeof Expect>;
+export declare const Capability: z.ZodEnum<{
+    type: "type";
+    observe: "observe";
+    screenshot: "screenshot";
+    tap: "tap";
+    scroll: "scroll";
+    swipe: "swipe";
+    press_key: "press_key";
+    list_apps: "list_apps";
+    open_app: "open_app";
+    open_url: "open_url";
+    wait_for: "wait_for";
+    run_shortcut: "run_shortcut";
+    device_action: "device_action";
+}>;
+export type Capability = z.infer<typeof Capability>;
+export declare const Key: z.ZodEnum<{
+    back: "back";
+    home: "home";
+    recents: "recents";
+    enter: "enter";
+    notifications: "notifications";
+}>;
+export type Key = z.infer<typeof Key>;

package/dist/core/protocol.js

@@ -0,0 +1,82 @@
+// Mobius protocol: the contract shared by host, Android app and iOS app.
+// Kotlin/Swift models must round-trip the golden fixtures in tests/fixtures.
+import { z } from 'zod';
+export const PROTOCOL_VERSION = 1;
+export const ErrorCode = z.enum([
+    'INVALID_INPUT', 'DEVICE_NOT_FOUND', 'DEVICE_OFFLINE', 'DEVICE_LOCKED', 'SERVICE_DISABLED',
+    'PERMISSION_REQUIRED', 'UNSUPPORTED_CAPABILITY', 'ELEMENT_NOT_FOUND', 'AMBIGUOUS_TARGET',
+    'STALE_ELEMENT', 'SECURE_WINDOW', 'APP_NOT_INSTALLED', 'POLICY_BLOCKED', 'APPROVAL_REQUIRED',
+    'APPROVAL_REJECTED', 'APPROVAL_EXPIRED', 'BUDGET_EXCEEDED', 'LOOP_DETECTED', 'RATE_LIMITED',
+    'DUPLICATE_ACTION', 'TIMEOUT', 'CANCELLED', 'OUTCOME_UNKNOWN', 'FOREGROUND_REQUIRED', 'INTERNAL',
+]);
+export const Platform = z.enum(['android', 'ios']);
+export const Framework = z.enum(['native', 'flutter', 'react_native', 'unknown']);
+export const TreeQuality = z.enum(['good', 'sparse', 'empty']);
+export const Bounds = z.object({ x: z.number(), y: z.number(), width: z.number(), height: z.number() });
+export const Role = z.enum([
+    'button', 'textbox', 'checkbox', 'switch', 'radio', 'image', 'text', 'list', 'tab', 'view',
+]);
+export const Element = z.object({
+    id: z.string(), // "o12:e5" — valid only against observation o12 (or re-resolvable)
+    role: Role,
+    text: z.string().nullable(),
+    label: z.string().nullable(), // content-desc / accessibility label
+    resource_id: z.string().nullable(),
+    clickable: z.boolean(),
+    long_clickable: z.boolean(),
+    enabled: z.boolean(),
+    focused: z.boolean(),
+    scrollable: z.boolean(),
+    editable: z.boolean(),
+    checked: z.boolean().nullable(),
+    selected: z.boolean(),
+    sensitive: z.boolean(), // true → text redacted at source
+    bounds: Bounds,
+    dup_index: z.number().int(), // nth element with identical role+text+label
+});
+export const Observation = z.object({
+    observation_id: z.string(),
+    device_id: z.string(),
+    platform: Platform,
+    foreground_app: z.string().nullable(),
+    screen: z.object({ width: z.number(), height: z.number(), rotation: z.number() }),
+    screen_hash: z.string(),
+    framework: Framework,
+    tree_quality: TreeQuality,
+    sources: z.array(z.enum(['a11y', 'flutter_vm', 'vision'])),
+    elements: z.array(Element),
+    untrusted_content: z.literal(true),
+    truncated: z.boolean(),
+    /** On-screen keyboard area when visible. Its keys are not listed as elements. */
+    keyboard: Bounds.nullable(),
+});
+export const MobiusErrorBody = z.object({
+    code: ErrorCode,
+    message: z.string(),
+    retryable: z.boolean(),
+    hint: z.string().optional(),
+});
+export const ActionStatus = z.enum(['succeeded', 'failed', 'blocked', 'pending_approval', 'outcome_unknown']);
+export const ActionResult = z.object({
+    ok: z.boolean(),
+    action_id: z.string(),
+    status: ActionStatus,
+    duration_ms: z.number(),
+    state_changed: z.boolean().nullable(),
+    foreground_app: z.string().nullable(),
+    observation_id: z.string().nullable(),
+    verified: z.boolean().nullable(),
+    message: z.string(),
+    error: MobiusErrorBody.optional(),
+});
+/** Post-action expectation; the host waits (state-based) until it holds or times out. */
+export const Expect = z.object({
+    text_visible: z.string().optional(),
+    app: z.string().optional(),
+    element_gone: z.string().optional(),
+}).strict();
+export const Capability = z.enum([
+    'observe', 'screenshot', 'tap', 'type', 'scroll', 'swipe', 'press_key',
+    'list_apps', 'open_app', 'open_url', 'wait_for', 'run_shortcut', 'device_action',
+]);
+export const Key = z.enum(['back', 'home', 'recents', 'enter', 'notifications']);

package/dist/execution/connector.d.ts

@@ -0,0 +1,82 @@
+import type { Bounds, Capability, ErrorCode, Framework, Key } from '../core/protocol.ts';
+/** Platform-neutral raw accessibility node, as produced by a connector before normalization. */
+export interface RawNode {
+    cls: string;
+    pkg: string;
+    text: string;
+    desc: string;
+    resourceId: string;
+    clickable: boolean;
+    longClickable: boolean;
+    enabled: boolean;
+    focused: boolean;
+    scrollable: boolean;
+    checkable: boolean;
+    checked: boolean;
+    selected: boolean;
+    password: boolean;
+    bounds: Bounds;
+    path: string;
+    children: RawNode[];
+}
+export interface RawScreen {
+    root: RawNode | null;
+    width: number;
+    height: number;
+    rotation: number;
+    foregroundApp: string | null;
+}
+export interface DeviceInfo {
+    device_id: string;
+    platform: 'android' | 'ios';
+    connector: string;
+    name: string;
+    model: string;
+    os_version: string;
+    online: boolean;
+    screen_on: boolean | null;
+    locked: boolean | null;
+}
+export type TapMode = 'single' | 'long' | 'double';
+export type Direction = 'up' | 'down' | 'left' | 'right';
+/** What every device backend implements. Add a platform = add a Connector. */
+export interface Connector {
+    readonly deviceId: string;
+    readonly platform: 'android' | 'ios';
+    /** Emulator or simulator (no real accounts or money on it). Undefined = unknown, treated as a real phone. */
+    readonly virtual?: boolean;
+    readonly capabilities: ReadonlySet<Capability>;
+    /** Known limitations surfaced to agents via device_capabilities. */
+    readonly limitations: readonly string[];
+    info(): Promise<DeviceInfo>;
+    /** Accessibility tree of the current screen; should return once the UI is idle. */
+    dump(): Promise<RawScreen>;
+    framework(pkg: string): Promise<Framework>;
+    screenshot(maxSize: number): Promise<{
+        data: string;
+        mimeType: string;
+    }>;
+    tap(x: number, y: number, mode: TapMode): Promise<void>;
+    type(text: string, submit: boolean): Promise<void>;
+    /** `direction` is finger movement; start defaults to screen centre. */
+    swipe(direction: Direction, from: {
+        x: number;
+        y: number;
+    } | null, distance: number | null): Promise<void>;
+    key(key: Key): Promise<void>;
+    openApp(appId: string): Promise<void>;
+    openUrl(url: string): Promise<void>;
+    listApps(): Promise<string[]>;
+    /** Driver operations beyond the core set (terminate, install, uninstall, clear_data, orientation, location, clipboard, info).
+     *  Optional: connectors without it report UNSUPPORTED_CAPABILITY. */
+    extra?(op: string, args?: Record<string, unknown>): Promise<any>;
+}
+export declare class MobiusError extends Error {
+    readonly code: ErrorCode;
+    readonly retryable: boolean;
+    readonly hint: string | undefined;
+    constructor(code: ErrorCode, message: string, opts?: {
+        retryable?: boolean;
+        hint?: string;
+    });
+}

package/dist/execution/connector.js

@@ -0,0 +1,11 @@
+export class MobiusError extends Error {
+    code;
+    retryable;
+    hint;
+    constructor(code, message, opts = {}) {
+        super(message);
+        this.code = code;
+        this.retryable = opts.retryable ?? false;
+        this.hint = opts.hint;
+    }
+}

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

@@ -0,0 +1,57 @@
+import type { Capability, Framework, Key } from '../../core/protocol.ts';
+import { type Connector, type DeviceInfo, type Direction, type RawScreen, type TapMode } from '../connector.ts';
+/** The driver binary: $MOBIUS_DRIVER_BIN, the one bundled in the npm package for this platform, or a source build. */
+export declare const driverPath: () => string;
+/** The driver binary is built (`cargo build --release` in drivers/mobiusagent-driver). */
+export declare const driverBuilt: () => boolean;
+/** iOS needs WebDriverAgent built and signed once (drivers/mobiusagent-driver/ios-agent/setup.sh). */
+export declare const iosAgentReady: () => boolean;
+export interface AgentDevice {
+    id: string;
+    platform: 'android' | 'ios';
+    type: 'emulator' | 'simulator' | 'real';
+    name: string;
+    model: string;
+    version: string;
+    state: string;
+}
+export declare class MobiusAgentDriver {
+    private proc;
+    private next;
+    private waiting;
+    private start;
+    call<T = any>(op: string, args?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    devices(): Promise<AgentDevice[]>;
+    close(): void;
+}
+export declare class MobiusAgentConnector implements Connector {
+    readonly platform: 'android' | 'ios';
+    readonly deviceId: string;
+    readonly capabilities: ReadonlySet<Capability>;
+    readonly limitations: readonly string[];
+    private size;
+    private fwCache;
+    private readonly drv;
+    private readonly dev;
+    constructor(drv: MobiusAgentDriver, dev: AgentDevice);
+    get virtual(): boolean;
+    private get d();
+    info(): Promise<DeviceInfo>;
+    dump(): Promise<RawScreen>;
+    framework(pkg: string): Promise<Framework>;
+    screenshot(maxSize: number): Promise<{
+        data: string;
+        mimeType: string;
+    }>;
+    tap(x: number, y: number, mode: TapMode): Promise<void>;
+    type(text: string, submit: boolean): Promise<void>;
+    swipe(direction: Direction, from: {
+        x: number;
+        y: number;
+    } | null, distance: number | null): Promise<void>;
+    key(key: Key): Promise<void>;
+    openApp(appId: string): Promise<void>;
+    openUrl(url: string): Promise<void>;
+    listApps(): Promise<string[]>;
+    extra(op: string, args?: Record<string, unknown>): Promise<any>;
+}