@anuraghq/mobius 0.0.0-stage → 0.1.0

package/dist/execution/session.d.ts

@@ -0,0 +1,101 @@
+import type { ActionResult, Element, Expect, Observation } from '../core/protocol.ts';
+import type { AuditLog } from '../observability/audit.ts';
+import { type PlaneContext } from '../infrastructure/plane.ts';
+import { type Connector } from './connector.ts';
+import { ObservationStore } from './observe.ts';
+import { type Approver, type Policy, type PolicyContext } from '../policy/policy.ts';
+/** Policy hook for one action. `targetId` is re-resolved after approval (screen may have changed). */
+export interface Guard {
+    ctx: Omit<PolicyContext, 'app' | 'target'>;
+    targetId?: string | undefined;
+    /** Coordinate actions: the point the finger lands on (resolved against the fresh screen). */
+    point?: {
+        x: number;
+        y: number;
+    } | undefined;
+    /** Human-readable action built from DEVICE state (element text), never from agent prose. */
+    describe: (target: Element | null) => string;
+}
+export declare const DEFAULT_ACTION_TIMEOUT_MS = 20000;
+export declare const DEFAULT_EXPECT_TIMEOUT_MS = 6000;
+/** Cold app launches (Flutter/RN on iOS) take longer than a tap to show; live run: Scapia was still on SpringBoard at 6 s. */
+export declare const LAUNCH_EXPECT_TIMEOUT_MS = 20000;
+/** Where to touch an element: the center of its on-screen part (an element partly above/left of the screen has negative
+ *  bounds; its raw center can be off-screen). Given the screen, a point not covered by a smaller clickable element inside
+ *  it: tapping a big card's center must not hit the item drawn there (live run: Swiggy's restaurant card opened a burger). */
+export declare const center: (e: Element, screen?: readonly Element[]) => {
+    x: number;
+    y: number;
+};
+export declare function expectationMet(obs: Observation, ex: Expect): boolean;
+/** One device: observation history + serialized action pipeline. */
+export declare class DeviceSession {
+    readonly connector: Connector;
+    readonly store: ObservationStore;
+    private readonly audit;
+    private readonly policy;
+    private readonly approver;
+    private queue;
+    private recent;
+    private readonly plane;
+    private verdict;
+    constructor(connector: Connector, audit: AuditLog, policy: Policy, approver: Approver, plane?: PlaneContext, persistIds?: boolean);
+    isBlockedApp(app: string | null): boolean;
+    /** Policy + approval gate. Returns the (re-resolved) target to act on. Throws MobiusError to stop. */
+    private gate;
+    /** Serialize work per device: one action at a time, no interleaved taps. */
+    private exclusive;
+    observe(): Promise<Observation>;
+    /** Re-observe until two consecutive screens hash the same (UI settled), bounded. State-based, no fixed sleeps. */
+    private settle;
+    /** Every element containing the point on the latest screen (overlays, the button below them, its labels). */
+    elementsAt(x: number, y: number): Element[];
+    /** Smallest clickable/editable element containing the point on the latest screen. */
+    elementAt(x: number, y: number): Element | null;
+    /** After tapping a field: wait (state-based, ≤2.5 s) until an editable element at that point has focus. */
+    waitForFocus(x: number, y: number): Promise<void>;
+    focusedField(): Element | null;
+    resolveTarget(element_id: string | undefined, x: number | undefined, y: number | undefined): {
+        el: {
+            id: string;
+            role: "button" | "textbox" | "checkbox" | "switch" | "radio" | "image" | "text" | "list" | "tab" | "view";
+            text: string | null;
+            label: string | null;
+            resource_id: string | null;
+            clickable: boolean;
+            long_clickable: boolean;
+            enabled: boolean;
+            focused: boolean;
+            scrollable: boolean;
+            editable: boolean;
+            checked: boolean | null;
+            selected: boolean;
+            sensitive: boolean;
+            bounds: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            };
+            dup_index: number;
+        };
+        x: number;
+        y: number;
+    } | {
+        x: number;
+        y: number;
+        el: null;
+    };
+    /**
+     * The single action pipeline: execute → settle → verify `expect` → audit.
+     * Never retries: the agent decides after seeing the fresh observation.
+     */
+    run(tool: string, auditParams: Record<string, unknown>, exec: (target: Element | null) => Promise<string>, opts?: {
+        expect?: Expect | undefined;
+        timeoutMs?: number | undefined;
+        guard?: Guard;
+        verifyMs?: number;
+        /** Built-in post-condition (e.g. typed text landed); combined with `expect`. Returns a failure reason or null. */
+        check?: (obs: Observation) => string | null;
+    }): Promise<ActionResult>;
+}

package/dist/execution/session.js

@@ -0,0 +1,304 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { isRevoked, killSwitchPath, newPlaneContext } from "../infrastructure/plane.js";
+import { MobiusError } from "./connector.js";
+import { buildObservation, ObservationStore } from "./observe.js";
+import { moneyOnScreen, newApprovalId } from "../policy/policy.js";
+export const DEFAULT_ACTION_TIMEOUT_MS = 20_000;
+export const DEFAULT_EXPECT_TIMEOUT_MS = 6_000;
+/** Cold app launches (Flutter/RN on iOS) take longer than a tap to show; live run: Scapia was still on SpringBoard at 6 s. */
+export const LAUNCH_EXPECT_TIMEOUT_MS = 20_000;
+/** Pause between re-reads while waiting for the screen. */
+const POLL_MS = 100;
+/** Text read from pixels, as an element the policy can judge like any label. */
+const drawnText = (text, bounds) => ({ id: 'drawn', role: 'text', text, label: null, resource_id: null,
+    clickable: false, long_clickable: false, enabled: true, focused: false, scrollable: false, editable: false, checked: null, selected: false,
+    sensitive: false, bounds, dup_index: 0 });
+/** Where to touch an element: the center of its on-screen part (an element partly above/left of the screen has negative
+ *  bounds; its raw center can be off-screen). Given the screen, a point not covered by a smaller clickable element inside
+ *  it: tapping a big card's center must not hit the item drawn there (live run: Swiggy's restaurant card opened a burger). */
+export const center = (e, screen) => {
+    const x1 = Math.max(e.bounds.x, 0), y1 = Math.max(e.bounds.y, 0);
+    const x2 = Math.max(e.bounds.x + e.bounds.width, x1), y2 = Math.max(e.bounds.y + e.bounds.height, y1);
+    const mid = { x: (x1 + x2) / 2, y: (y1 + y2) / 2 };
+    if (!screen)
+        return mid;
+    const inside = (o) => o.bounds.x >= e.bounds.x && o.bounds.y >= e.bounds.y && o.bounds.x + o.bounds.width <= e.bounds.x + e.bounds.width
+        && o.bounds.y + o.bounds.height <= e.bounds.y + e.bounds.height && o.bounds.width * o.bounds.height < e.bounds.width * e.bounds.height;
+    const kids = screen.filter(o => o !== e && o.id !== e.id && (o.clickable || o.editable) && inside(o));
+    if (!kids.length)
+        return mid;
+    const hit = (p) => kids.some(k => p.x >= k.bounds.x && p.x <= k.bounds.x + k.bounds.width && p.y >= k.bounds.y && p.y <= k.bounds.y + k.bounds.height);
+    const at = (fx, fy) => ({ x: x1 + (x2 - x1) * fx, y: y1 + (y2 - y1) * fy });
+    for (const [fx, fy] of [[0.5, 0.5], [0.5, 0.12], [0.12, 0.5], [0.88, 0.5], [0.5, 0.88], [0.12, 0.12], [0.88, 0.12], [0.12, 0.88], [0.88, 0.88], [0.3, 0.12], [0.7, 0.12]]) {
+        const p = at(fx, fy);
+        if (!hit(p))
+            return p;
+    }
+    return mid; // fully covered: the children are the target in practice
+};
+function withTimeout(p, ms, what) {
+    let timer;
+    return Promise.race([
+        p.finally(() => clearTimeout(timer)),
+        new Promise((_, rej) => {
+            timer = setTimeout(() => rej(new MobiusError('OUTCOME_UNKNOWN', `${what} did not finish within ${ms} ms`, {
+                hint: 'The action may or may not have happened. Call observe before retrying.',
+            })), ms);
+        }),
+    ]);
+}
+export function expectationMet(obs, ex) {
+    const has = (t) => obs.elements.some(e => (e.text ?? '').includes(t) || (e.label ?? '').includes(t));
+    if (ex.text_visible !== undefined && !has(ex.text_visible))
+        return false;
+    if (ex.app !== undefined && obs.foreground_app !== ex.app)
+        return false;
+    if (ex.element_gone !== undefined && obs.elements.some(e => e.id === ex.element_gone))
+        return false;
+    return true;
+}
+/** One device: observation history + serialized action pipeline. */
+export class DeviceSession {
+    connector;
+    store;
+    audit;
+    policy;
+    approver;
+    queue = Promise.resolve();
+    recent = [];
+    plane;
+    verdict = null;
+    constructor(connector, audit, policy, approver, plane = newPlaneContext(), persistIds = false) {
+        this.store = new ObservationStore(persistIds ? connector.deviceId : undefined);
+        this.connector = connector;
+        this.plane = plane;
+        this.audit = audit;
+        this.policy = policy;
+        this.approver = approver;
+    }
+    isBlockedApp(app) { return this.policy.appBlocked(app); }
+    /** Policy + approval gate. Returns the (re-resolved) target to act on. Throws MobiusError to stop. */
+    async gate(tool, guard) {
+        // Time of check = time of use: the app may have changed the screen since the agent read it ("Add to cart" becomes
+        // "Pay ₹999"). Re-read now and decide on what the finger will actually hit. A changed target is refused as stale.
+        if (guard.ctx.mutating && (guard.targetId || guard.point))
+            await this.observe();
+        const latest = this.store.latest();
+        let target = guard.targetId ? this.store.resolve(guard.targetId) : guard.point ? this.elementAt(guard.point.x, guard.point.y) : null;
+        const p = guard.point ?? (target ? center(target, latest?.elements) : null);
+        const under = p ? this.elementsAt(p.x, p.y) : [];
+        // Pixels, not just labels: on a screen showing an amount due, read the text actually drawn where the finger lands
+        // (OCR), so a Pay button can't hide behind an accessibility label that says "Close".
+        if (guard.ctx.mutating && p && this.connector.extra && moneyOnScreen(latest?.elements)) {
+            const drawn = await this.connector.extra('ocr', {}).catch(() => null);
+            const b = target?.bounds;
+            for (const t of drawn?.text ?? []) {
+                const [x = 0, y = 0, w = 0, h = 0] = (t.box ?? []);
+                const cx = x + w / 2, cy = y + h / 2;
+                const hit = b ? cx >= b.x && cx <= b.x + b.width && cy >= b.y && cy <= b.y + b.height
+                    : p.x >= x - 16 && p.x <= x + w + 16 && p.y >= y - 16 && p.y <= y + h + 16;
+                if (hit && t.text)
+                    under.push(drawnText(String(t.text), { x, y, width: w, height: h }));
+            }
+        }
+        if (guard.ctx.mutating) {
+            if (existsSync(killSwitchPath()))
+                throw new MobiusError('POLICY_BLOCKED', 'Kill switch engaged: all agent actions are stopped', { hint: 'A human ran `mobius stop`. Stop and tell the user.' });
+            const pl = this.plane;
+            if (pl.actions >= pl.max_actions)
+                throw new MobiusError('POLICY_BLOCKED', `Action quota reached (${pl.max_actions} per session)`, { hint: 'Stop and report progress to the user.' });
+            const ses = pl.session();
+            if (ses && 'invalid' in ses)
+                throw new MobiusError('POLICY_BLOCKED', `Agent session token rejected: ${ses.invalid}`, { hint: 'Ask the operator for a fresh session token.' });
+            if (!ses && pl.require_session)
+                throw new MobiusError('POLICY_BLOCKED', 'This Mobius requires a signed agent session', { hint: 'Ask the operator for a session token (mobius session issue).' });
+            if (ses && isRevoked(ses.jti))
+                throw new MobiusError('POLICY_BLOCKED', 'Agent session revoked by the operator', { hint: 'Stop and tell the user.' });
+            if (ses && ses.exp <= Date.now() / 1000)
+                throw new MobiusError('POLICY_BLOCKED', 'Agent session expired', { hint: 'Ask the operator for a fresh session token.' });
+            if (ses?.policy_version && ses.policy_version !== this.policy.config.version) {
+                throw new MobiusError('POLICY_BLOCKED', `Session was issued for policy ${ses.policy_version}, but Mobius runs ${this.policy.config.version}`, { hint: 'The operator must re-issue the session for the current policy.' });
+            }
+            if (pl.max_minutes && Date.now() - pl.started > pl.max_minutes * 60_000)
+                throw new MobiusError('POLICY_BLOCKED', `Session time limit reached (${pl.max_minutes} min)`, { hint: 'Stop and report progress to the user.' });
+        }
+        const v = this.policy.evaluate({ ...guard.ctx, tool, app: latest?.foreground_app ?? null, target, screen: latest?.elements, under });
+        this.verdict = v;
+        const { decision, reason, action_class } = v;
+        if (decision === 'blocked')
+            throw new MobiusError('POLICY_BLOCKED', `Blocked by policy: ${reason}`, { hint: 'Ask the user to do this step themselves.' });
+        if (decision === 'allow')
+            return target;
+        const req = { id: newApprovalId(), device_id: this.connector.deviceId, app: latest?.foreground_app ?? null, tool, summary: guard.describe(target), reason, action_class, virtual_device: this.connector.virtual };
+        const outcome = await this.approver.request(req, this.policy.config.approval_timeout_s);
+        if (outcome === 'rejected')
+            throw new MobiusError('APPROVAL_REJECTED', `User rejected: ${req.summary}`, { hint: 'Do not retry. Ask the user what they want instead.' });
+        if (outcome === 'expired')
+            throw new MobiusError('APPROVAL_EXPIRED', `No decision within ${this.policy.config.approval_timeout_s}s: ${req.summary}`, { retryable: true });
+        // Time passed while the human decided: confirm the approved target is still the one on screen.
+        if (guard.targetId) {
+            await this.observe();
+            target = this.store.resolve(guard.targetId);
+            if (guard.describe(target) !== req.summary) {
+                throw new MobiusError('STALE_ELEMENT', 'Screen changed after approval; the approved target is no longer the same', { retryable: true, hint: 'Observe again; a new approval will be requested.' });
+            }
+        }
+        return target;
+    }
+    /** Serialize work per device: one action at a time, no interleaved taps. */
+    exclusive(fn) {
+        const next = this.queue.then(fn, fn);
+        this.queue = next.catch(() => undefined);
+        return next;
+    }
+    async observe() {
+        const screen = await this.connector.dump();
+        const fw = screen.foregroundApp ? await this.connector.framework(screen.foregroundApp) : 'unknown';
+        const { obs, fps } = buildObservation(screen, this.connector.deviceId, this.connector.platform, this.store.nextId(), fw);
+        this.store.add(obs, fps);
+        return obs;
+    }
+    /** Re-observe until two consecutive screens hash the same (UI settled), bounded. State-based, no fixed sleeps. */
+    async settle(deadline) {
+        let prev = await this.observe();
+        while (Date.now() < deadline) {
+            await new Promise(r => setTimeout(r, POLL_MS));
+            const next = await this.observe();
+            if (next.screen_hash === prev.screen_hash)
+                return next;
+            prev = next;
+        }
+        return prev;
+    }
+    /** Every element containing the point on the latest screen (overlays, the button below them, its labels). */
+    elementsAt(x, y) {
+        return (this.store.latest()?.elements ?? []).filter(e => x >= e.bounds.x && x <= e.bounds.x + e.bounds.width && y >= e.bounds.y && y <= e.bounds.y + e.bounds.height);
+    }
+    /** Smallest clickable/editable element containing the point on the latest screen. */
+    elementAt(x, y) {
+        const hits = (this.store.latest()?.elements ?? []).filter(e => (e.clickable || e.editable || e.long_clickable)
+            && x >= e.bounds.x && x <= e.bounds.x + e.bounds.width && y >= e.bounds.y && y <= e.bounds.y + e.bounds.height);
+        return hits.sort((a, b) => a.bounds.width * a.bounds.height - b.bounds.width * b.bounds.height)[0] ?? null;
+    }
+    /** After tapping a field: wait (state-based, ≤2.5 s) until an editable element at that point has focus. */
+    async waitForFocus(x, y) {
+        const until = Date.now() + 2_500;
+        while (Date.now() < until) {
+            const o = await this.observe();
+            const f = o.elements.find(e => e.editable && e.focused && x >= e.bounds.x && x <= e.bounds.x + e.bounds.width && y >= e.bounds.y && y <= e.bounds.y + e.bounds.height);
+            if (f)
+                return;
+        }
+    }
+    focusedField() {
+        return this.store.latest()?.elements.find(e => e.editable && e.focused) ?? null;
+    }
+    resolveTarget(element_id, x, y) {
+        if (element_id) {
+            const el = this.store.resolve(element_id);
+            if (!el.enabled)
+                throw new MobiusError('ELEMENT_NOT_FOUND', `${element_id} is disabled`, { hint: 'Wait for it to enable or pick another element.' });
+            return { ...center(el, this.store.latest()?.elements), el };
+        }
+        if (x !== undefined && y !== undefined) {
+            const s = this.store.latest()?.screen;
+            if (s && s.width && (x < 0 || y < 0 || x > s.width || y > s.height)) {
+                throw new MobiusError('INVALID_INPUT', `(${x}, ${y}) is outside the ${s.width}x${s.height} screen`);
+            }
+            return { x, y, el: null };
+        }
+        throw new MobiusError('INVALID_INPUT', 'Give element_id, or both x and y');
+    }
+    /**
+     * The single action pipeline: execute → settle → verify `expect` → audit.
+     * Never retries: the agent decides after seeing the fresh observation.
+     */
+    run(tool, auditParams, exec, opts = {}) {
+        return this.exclusive(async () => {
+            const action_id = `act_${randomUUID().slice(0, 8)}`;
+            const t0 = Date.now();
+            let preHash = this.store.latest()?.screen_hash ?? null;
+            const loopKey = `${tool}|${JSON.stringify(auditParams)}|${preHash}`;
+            let result;
+            try {
+                // Loop guard: same action on the same unchanged screen 3 times in a row.
+                const last2 = this.recent.slice(-2);
+                if (last2.length === 2 && last2.every(r => r.key === loopKey && r.changed === false)) {
+                    throw new MobiusError('LOOP_DETECTED', `${tool} repeated 3x on an unchanged screen`, { hint: 'Change strategy: observe, scroll, take a screenshot, or ask the user.' });
+                }
+                this.verdict = null;
+                const target = opts.guard ? await this.gate(tool, opts.guard) : null;
+                if (opts.guard?.ctx.mutating)
+                    this.plane.actions++;
+                preHash = this.store.latest()?.screen_hash ?? preHash;
+                const message = await withTimeout(exec(target), opts.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS, tool);
+                const verifying = !!opts.expect || !!opts.check;
+                const deadline = Date.now() + (verifying ? opts.verifyMs ?? DEFAULT_EXPECT_TIMEOUT_MS : 2_500);
+                let obs = await this.settle(Math.min(deadline, Date.now() + 2_500));
+                let verified = null;
+                let why = '';
+                const evaluate = (o) => {
+                    const bad = opts.check?.(o) ?? null;
+                    if (bad) {
+                        why = bad;
+                        return false;
+                    }
+                    if (opts.expect && !expectationMet(o, opts.expect)) {
+                        why = `expectation not met: ${JSON.stringify(opts.expect)}`;
+                        return false;
+                    }
+                    return true;
+                };
+                if (verifying) {
+                    verified = evaluate(obs);
+                    while (!verified && Date.now() < deadline) {
+                        await new Promise(r => setTimeout(r, POLL_MS)); // yield: a fast device must not starve timers (and the CPU)
+                        obs = await this.observe();
+                        verified = evaluate(obs);
+                    }
+                }
+                result = {
+                    ok: verified !== false,
+                    action_id,
+                    status: verified === false ? 'failed' : 'succeeded',
+                    duration_ms: Date.now() - t0,
+                    state_changed: preHash === null ? null : preHash !== obs.screen_hash,
+                    foreground_app: obs.foreground_app,
+                    observation_id: obs.observation_id,
+                    verified,
+                    message: verified === false ? `${message}, but ${why}` : message,
+                };
+            }
+            catch (e) {
+                const err = e instanceof MobiusError ? e : new MobiusError('INTERNAL', e.message);
+                result = {
+                    ok: false, action_id,
+                    status: err.code === 'OUTCOME_UNKNOWN' ? 'outcome_unknown'
+                        : ['POLICY_BLOCKED', 'APPROVAL_REJECTED', 'APPROVAL_EXPIRED'].includes(err.code) ? 'blocked' : 'failed',
+                    duration_ms: Date.now() - t0, state_changed: null, foreground_app: null, observation_id: null, verified: null,
+                    message: err.message,
+                    error: { code: err.code, message: err.message, retryable: err.retryable, ...(err.hint ? { hint: err.hint } : {}) },
+                };
+            }
+            this.recent.push({ key: loopKey, changed: result.state_changed });
+            if (this.recent.length > 10)
+                this.recent.shift();
+            try {
+                this.audit.record({
+                    action_id, device_id: this.connector.deviceId, tool, params: auditParams, status: result.status,
+                    error_code: result.error?.code ?? null, duration_ms: result.duration_ms,
+                    agent: (() => { const ses = this.plane.session(); return ses && !('invalid' in ses) ? ses.sub : this.plane.agent(); })(),
+                    agent_session: (() => { const ses = this.plane.session(); return ses && !('invalid' in ses) ? ses.jti : null; })(),
+                    session_id: this.plane.session_id,
+                    decision: this.verdict?.decision ?? null, rule_id: this.verdict?.rule_id ?? null,
+                    action_class: this.verdict?.action_class ?? null, amount: this.verdict?.amount ?? null,
+                });
+            }
+            catch (e) {
+                process.stderr.write(JSON.stringify({ level: 'error', msg: 'audit write failed', err: String(e) }) + '\n');
+            }
+            return result;
+        });
+    }
+}

package/dist/infrastructure/plane.d.ts

@@ -0,0 +1,25 @@
+import type { SessionClaims } from '../observability/signing.ts';
+/** Shared across all devices of one server process: who the agent is, and its limits. */
+export interface PlaneContext {
+    session_id: string;
+    /** MCP client name/version once the agent has connected. */
+    agent: () => string | null;
+    /** Mutating actions so far, and when the session began. */
+    actions: number;
+    started: number;
+    max_actions: number;
+    /** 0 = no limit. */
+    max_minutes: number;
+    /** The verified signed session of the agent making the current call (or an invalid-token reason). */
+    session: () => SessionClaims | {
+        invalid: string;
+    } | null;
+    /** Refuse state-changing actions from agents without a valid signed session (MOBIUS_REQUIRE_SESSION=1). */
+    require_session: boolean;
+}
+export declare const newPlaneContext: (agent?: () => string | null) => PlaneContext;
+/** `mobius stop` creates this file; every state-changing action is refused until `mobius resume`. */
+export declare const killSwitchPath: () => string;
+/** `mobius session revoke <jti>` appends here; a revoked session can't act, even before it expires. */
+export declare const revokedPath: () => string;
+export declare const isRevoked: (jti: string) => boolean;

package/dist/infrastructure/plane.js

@@ -0,0 +1,16 @@
+// Infrastructure: session-wide limits and the kill switch, shared by every device a server drives.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { mobiusHome } from "../observability/audit.js";
+export const newPlaneContext = (agent = () => null) => ({
+    session_id: `ses_${randomUUID().slice(0, 8)}`, agent, actions: 0, started: Date.now(),
+    max_actions: Number(process.env.MOBIUS_MAX_ACTIONS ?? 1000), max_minutes: Number(process.env.MOBIUS_MAX_SESSION_MIN ?? 0),
+    session: () => null, require_session: process.env.MOBIUS_REQUIRE_SESSION === '1',
+});
+/** `mobius stop` creates this file; every state-changing action is refused until `mobius resume`. */
+export const killSwitchPath = () => join(mobiusHome(), 'STOP');
+/** `mobius session revoke <jti>` appends here; a revoked session can't act, even before it expires. */
+export const revokedPath = () => join(mobiusHome(), 'revoked');
+// ponytail: re-read per check (a few lines, like the kill switch); index it if the list ever reaches thousands.
+export const isRevoked = (jti) => existsSync(revokedPath()) && readFileSync(revokedPath(), 'utf8').split('\n').some(l => l.trim() === jti);

package/dist/infrastructure/registry.d.ts

@@ -0,0 +1,19 @@
+import { type Connector } from '../execution/connector.ts';
+import { DeviceSession } from '../execution/session.ts';
+import type { AuditLog } from '../observability/audit.ts';
+import type { Approver, Policy } from '../policy/policy.ts';
+import { type PlaneContext } from './plane.ts';
+/** Device registry. `discover` is injectable so tests run without real devices. */
+export declare class Mobius {
+    private sessions;
+    private readonly discover;
+    readonly audit: AuditLog;
+    readonly policy: Policy;
+    readonly approver: Approver;
+    /** Real CLI only: keep element ids resolvable across Mobius restarts (identity hashes on disk, never screen text). */
+    persistIds: boolean;
+    readonly plane: PlaneContext;
+    constructor(discover: () => Promise<Connector[]>, audit: AuditLog, policy: Policy, approver: Approver, plane?: PlaneContext);
+    refresh(): Promise<DeviceSession[]>;
+    session(deviceId?: string): Promise<DeviceSession>;
+}

package/dist/infrastructure/registry.js

@@ -0,0 +1,49 @@
+// Infrastructure: which devices exist and one session per device. Drivers are discovered through `discover`.
+import { MobiusError } from "../execution/connector.js";
+import { DeviceSession } from "../execution/session.js";
+import { newPlaneContext } from "./plane.js";
+/** Device registry. `discover` is injectable so tests run without real devices. */
+export class Mobius {
+    sessions = new Map();
+    discover;
+    audit;
+    policy;
+    approver;
+    /** Real CLI only: keep element ids resolvable across Mobius restarts (identity hashes on disk, never screen text). */
+    persistIds = false;
+    plane;
+    constructor(discover, audit, policy, approver, plane = newPlaneContext()) {
+        this.plane = plane;
+        this.discover = discover;
+        this.audit = audit;
+        this.policy = policy;
+        this.approver = approver;
+    }
+    async refresh() {
+        const found = await this.discover();
+        const ids = new Set(found.map(c => c.deviceId));
+        for (const id of this.sessions.keys())
+            if (!ids.has(id))
+                this.sessions.delete(id);
+        for (const c of found)
+            if (!this.sessions.has(c.deviceId))
+                this.sessions.set(c.deviceId, new DeviceSession(c, this.audit, this.policy, this.approver, this.plane, this.persistIds));
+        return [...this.sessions.values()];
+    }
+    async session(deviceId) {
+        let s = deviceId ? this.sessions.get(deviceId) : undefined;
+        if (!s) {
+            const all = await this.refresh();
+            s = deviceId ? this.sessions.get(deviceId) : all.length === 1 ? all[0] : undefined;
+            if (!s) {
+                if (deviceId)
+                    throw new MobiusError('DEVICE_NOT_FOUND', `No device "${deviceId}"`, { hint: `Available: ${all.map(a => a.connector.deviceId).join(', ') || 'none'}` });
+                throw new MobiusError(all.length ? 'INVALID_INPUT' : 'DEVICE_NOT_FOUND', all.length ? `${all.length} devices connected; pass device_id` : 'No devices connected', { hint: all.length ? `One of: ${all.map(a => a.connector.deviceId).join(', ')}` : 'Start an emulator/simulator or plug in a device, then call device_list.' });
+            }
+        }
+        // A fresh process: read the screen once, so element ids from an earlier process can be resolved right away.
+        if (this.persistIds && !s.store.latest())
+            await s.observe();
+        return s;
+    }
+}

package/dist/interface/engine.d.ts

@@ -0,0 +1,24 @@
+import type { Mobius } from '../infrastructure/registry.ts';
+import type { SessionClaims } from '../observability/signing.ts';
+export interface ToolInfo {
+    name: string;
+    description?: string;
+    inputSchema: unknown;
+}
+export interface EngineResult {
+    ok: boolean;
+    result: unknown;
+    image?: {
+        data: string;
+        mimeType: string;
+    };
+}
+export interface Engine {
+    tools(): Promise<ToolInfo[]>;
+    /** Run one tool as `agent` (recorded in the audit trail). */
+    call(tool: string, args: Record<string, unknown>, agent?: string, session?: SessionClaims | {
+        invalid: string;
+    } | null): Promise<EngineResult>;
+    close(): Promise<void>;
+}
+export declare function createEngine(mobius: Mobius): Promise<Engine>;

package/dist/interface/engine.js

@@ -0,0 +1,38 @@
+// Agent interface: one engine behind every front door (MCP, REST, SDKs). Each call goes through the same tool layer,
+// so policy, approvals, verification and audit are identical whichever way an agent connects.
+// ponytail: the engine reuses the MCP tool handlers in-process; split them into plain functions if a front door ever
+// needs something MCP can't express.
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createServer } from "./mcp.js";
+export async function createEngine(mobius) {
+    const server = createServer(mobius);
+    const [a, b] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: 'mobius-engine', version: '0.1.0' });
+    await Promise.all([server.connect(a), client.connect(b)]);
+    // Identity per call, carried with the call itself (not a shared variable), so calls on different devices run at the
+    // same time and each audit entry still names its own agent. Each device's own queue keeps its actions in order.
+    const who = new AsyncLocalStorage();
+    mobius.plane.agent = () => who.getStore()?.agent ?? null;
+    mobius.plane.session = () => who.getStore()?.session ?? null;
+    return {
+        async tools() { return (await client.listTools()).tools.map(t => ({ name: t.name, ...(t.description ? { description: t.description } : {}), inputSchema: t.inputSchema })); },
+        call(tool, args, agent, session) {
+            return who.run({ agent: agent ?? null, session: session ?? null }, async () => {
+                const r = await client.callTool({ name: tool, arguments: args }, undefined, { timeout: 300_000 });
+                const text = r.content?.find((c) => c.type === 'text')?.text ?? '{}';
+                const img = r.content?.find((c) => c.type === 'image');
+                let result;
+                try {
+                    result = JSON.parse(text);
+                }
+                catch {
+                    result = { raw: text };
+                }
+                return { ok: !r.isError, result, ...(img ? { image: { data: img.data, mimeType: img.mimeType } } : {}) };
+            });
+        },
+        async close() { await client.close(); },
+    };
+}

package/dist/interface/http.d.ts

@@ -0,0 +1,4 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import type { AuditLog } from '../observability/audit.ts';
+import type { Engine } from './engine.ts';
+export declare function createHttpServer(engine: Engine, audit: AuditLog, token: string, sessionKey?: string): import("http").Server<typeof IncomingMessage, typeof ServerResponse>;