@rynx-ai/server 0.1.0 → 0.1.10-beta.2

package/dist/session-emulator-service.d.ts

@@ -0,0 +1,167 @@
+import type { RemoteRuntimeEmulatorBackend, RemoteRuntimeEmulatorButtonParams, RemoteRuntimeEmulatorGesturePoint, RemoteRuntimeEmulatorTypeMode, RemoteRuntimeSessionEmulatorBinding, RemoteRuntimeSessionEmulatorDevice } from "@rynx-ai/protocol/remote-runtime-rpc";
+import type { RemoteRuntimeEmulatorHost } from "./remote-runtime-dispatcher.js";
+export interface SessionEmulatorBindingRecord {
+    sessionId: string;
+    bindingId: string;
+    backend: RemoteRuntimeEmulatorBackend;
+    deviceId: string;
+    deviceName?: string;
+    attachedAt: string;
+}
+export interface SessionEmulatorBindingStore {
+    get(sessionId: string): SessionEmulatorBindingRecord | undefined | Promise<SessionEmulatorBindingRecord | undefined>;
+    findByDevice(backend: RemoteRuntimeEmulatorBackend, deviceId: string): SessionEmulatorBindingRecord | undefined | Promise<SessionEmulatorBindingRecord | undefined>;
+    /** Atomically replace this Session's binding while preserving device uniqueness. */
+    bind(record: SessionEmulatorBindingRecord): void | Promise<void>;
+    release(sessionId: string, bindingId: string): boolean | Promise<boolean>;
+    releaseSession(sessionId: string): boolean | Promise<boolean>;
+    releaseDevice(backend: RemoteRuntimeEmulatorBackend, deviceId: string): number | Promise<number>;
+}
+export declare class SessionEmulatorBindingConflictError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export type SessionEmulatorServiceErrorCode = "session_not_found" | "device_not_found" | "device_in_use" | "binding_mismatch" | "emulator_unavailable";
+export declare class SessionEmulatorServiceError extends Error {
+    readonly code: SessionEmulatorServiceErrorCode;
+    constructor(code: SessionEmulatorServiceErrorCode, message: string, options?: ErrorOptions);
+}
+export interface SessionEmulatorServiceOptions {
+    emulator: RemoteRuntimeEmulatorHost & {
+        frame?(input: {
+            device?: string;
+        }): Promise<{
+            ok: true;
+            backend: RemoteRuntimeEmulatorBackend;
+            device: string;
+            contentType: "image/png";
+            data: Buffer;
+        }>;
+        imageStream?(input: {
+            device?: string;
+            signal?: AbortSignal;
+        }): Promise<{
+            ok: true;
+            backend: RemoteRuntimeEmulatorBackend;
+            device: string;
+            contentType: "image/jpeg";
+            nextFrame(): Promise<Buffer>;
+            close(): void;
+        }>;
+        liveTouch?(input: {
+            device?: string;
+            signal?: AbortSignal;
+        }): Promise<{
+            ok: true;
+            backend: RemoteRuntimeEmulatorBackend;
+            device: string;
+            send(point: RemoteRuntimeEmulatorGesturePoint): void;
+            close(): void;
+        }>;
+    };
+    store: SessionEmulatorBindingStore;
+    sessions: {
+        exists(sessionId: string): boolean | Promise<boolean>;
+    };
+    now?: () => Date;
+    bindingId?: () => string;
+}
+export interface SessionEmulatorSurface {
+    readonly sessionId: string;
+    readonly bindingId: string;
+    readonly backend: RemoteRuntimeEmulatorBackend;
+    readonly deviceId: string;
+    readonly format: "png" | "jpeg";
+    capture(): Promise<Buffer>;
+    touch(point: RemoteRuntimeEmulatorGesturePoint): Promise<void>;
+    close(): void;
+}
+/** Runtime-owned authority for the one-Session/one-device Emulator binding. */
+export declare class SessionEmulatorService {
+    private readonly options;
+    private readonly now;
+    private readonly createBindingId;
+    private readonly sessionOperations;
+    private readonly deviceOperations;
+    private readonly deviceReservations;
+    constructor(options: SessionEmulatorServiceOptions);
+    getState(input: {
+        sessionId: string;
+    }): Promise<RemoteRuntimeSessionEmulatorBinding | null>;
+    listDevices(input: {
+        sessionId: string;
+    }): Promise<RemoteRuntimeSessionEmulatorDevice[]>;
+    private listDevicesUnlocked;
+    attach(input: {
+        sessionId: string;
+        device: string;
+    }): Promise<RemoteRuntimeSessionEmulatorBinding>;
+    private attachUnlocked;
+    detach(input: {
+        sessionId: string;
+        bindingId: string;
+    }): Promise<{
+        released: true;
+    }>;
+    tap(input: {
+        sessionId: string;
+        bindingId: string;
+        x: number;
+        y: number;
+    }): Promise<unknown>;
+    type(input: {
+        sessionId: string;
+        bindingId: string;
+        text: string;
+        mode?: RemoteRuntimeEmulatorTypeMode;
+    }): Promise<unknown>;
+    button(input: {
+        sessionId: string;
+        bindingId: string;
+        name?: RemoteRuntimeEmulatorButtonParams["name"];
+    }): Promise<unknown>;
+    rotate(input: {
+        sessionId: string;
+        bindingId: string;
+        orientation: string;
+    }): Promise<unknown>;
+    launch(input: {
+        sessionId: string;
+        bindingId: string;
+        appId: string;
+    }): Promise<unknown>;
+    gesture(input: {
+        sessionId: string;
+        bindingId: string;
+        points: RemoteRuntimeEmulatorGesturePoint[];
+    }): Promise<unknown>;
+    frame(input: {
+        sessionId: string;
+        bindingId: string;
+    }): Promise<{
+        ok: true;
+        backend: RemoteRuntimeEmulatorBackend;
+        device: string;
+        contentType: "image/png";
+        data: Buffer;
+    }>;
+    openSurface(input: {
+        sessionId: string;
+        bindingId: string;
+        signal?: AbortSignal;
+    }): Promise<SessionEmulatorSurface>;
+    cleanupSession(sessionId: string): Promise<void>;
+    releaseDevice(backend: RemoteRuntimeEmulatorBackend, deviceId: string): Promise<void>;
+    /** Serialize destructive device lifecycle commands with Session attachment. */
+    stopDevice(input: {
+        action: "kill" | "shutdown";
+        device?: string;
+    }): Promise<unknown>;
+    private withBinding;
+    private serial;
+    private withDeviceReservations;
+    private acquireDevice;
+    private requireBinding;
+    private requireSession;
+    private devices;
+    private projectBinding;
+}

package/dist/session-emulator-service.js

@@ -0,0 +1,464 @@
+import { randomUUID } from "node:crypto";
+export class SessionEmulatorBindingConflictError extends Error {
+    constructor(message = "Emulator device is already bound to another Session", options) {
+        super(message, options);
+        this.name = "SessionEmulatorBindingConflictError";
+    }
+}
+export class SessionEmulatorServiceError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "SessionEmulatorServiceError";
+    }
+}
+/** Runtime-owned authority for the one-Session/one-device Emulator binding. */
+export class SessionEmulatorService {
+    options;
+    now;
+    createBindingId;
+    sessionOperations = new Map();
+    deviceOperations = new Map();
+    deviceReservations = new Map();
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? (() => new Date());
+        this.createBindingId = options.bindingId ?? randomUUID;
+    }
+    async getState(input) {
+        return this.serial(input.sessionId, async () => {
+            await this.requireSession(input.sessionId);
+            const record = await this.options.store.get(input.sessionId);
+            if (!record)
+                return null;
+            return this.projectBinding(record, await this.devices());
+        });
+    }
+    async listDevices(input) {
+        return this.serial(input.sessionId, () => this.listDevicesUnlocked(input));
+    }
+    async listDevicesUnlocked(input) {
+        await this.requireSession(input.sessionId);
+        const current = await this.options.store.get(input.sessionId);
+        const devices = await this.devices();
+        const visible = [];
+        for (const device of devices) {
+            const reservation = this.deviceReservations.get(deviceKey(device.backend, device.id));
+            if (reservation && reservation !== input.sessionId)
+                continue;
+            const owner = await this.options.store.findByDevice(device.backend, device.id);
+            if (owner && owner.sessionId !== input.sessionId)
+                continue;
+            const attached = current?.backend === device.backend && current.deviceId === device.id;
+            if (!attached && device.isAvailable === false)
+                continue;
+            visible.push({
+                ...device,
+                availability: attached ? "attached" : "available",
+            });
+        }
+        return visible;
+    }
+    async attach(input) {
+        return this.serial(input.sessionId, () => this.attachUnlocked(input));
+    }
+    async attachUnlocked(input) {
+        await this.requireSession(input.sessionId);
+        const devices = await this.devices();
+        const matches = devices.filter((device) => device.id === input.device);
+        if (matches.length !== 1) {
+            throw new SessionEmulatorServiceError("device_not_found", matches.length === 0
+                ? "Emulator device was not found on this Runtime"
+                : "Emulator device selector is ambiguous on this Runtime");
+        }
+        const device = matches[0];
+        const current = await this.options.store.get(input.sessionId);
+        if (current?.backend === device.backend && current.deviceId === device.id) {
+            return this.projectBinding(current, devices);
+        }
+        const record = {
+            sessionId: input.sessionId,
+            bindingId: this.createBindingId(),
+            backend: device.backend,
+            deviceId: device.id,
+            deviceName: device.name,
+            attachedAt: this.now().toISOString(),
+        };
+        const reservations = [
+            { backend: device.backend, deviceId: device.id },
+            ...(current ? [{ backend: current.backend, deviceId: current.deviceId }] : []),
+        ];
+        return this.withDeviceReservations(input.sessionId, reservations, async () => {
+            const owner = await this.options.store.findByDevice(device.backend, device.id);
+            if (owner && owner.sessionId !== input.sessionId) {
+                throw new SessionEmulatorServiceError("device_in_use", "Emulator device is already bound to another Session");
+            }
+            let attachment;
+            try {
+                attachment = await this.options.emulator.attach(device.id);
+                const attachedIdentityMatches = attachment.deviceUdid === device.id || (device.backend === "android" &&
+                    typeof attachment.deviceName === "string" &&
+                    attachment.deviceName === device.name);
+                if (!attachedIdentityMatches) {
+                    throw new Error("Emulator host attached a different device");
+                }
+            }
+            catch (error) {
+                throw new SessionEmulatorServiceError("emulator_unavailable", "Emulator could not be attached", { cause: error });
+            }
+            try {
+                // Publish ownership only after the physical attach succeeds. The
+                // in-process device reservations provide exclusivity during the slow
+                // boot/helper work, so a failed replacement needs no visible rollback.
+                await this.options.store.bind(record);
+            }
+            catch (error) {
+                if (error instanceof SessionEmulatorBindingConflictError) {
+                    throw new SessionEmulatorServiceError("device_in_use", error.message, { cause: error });
+                }
+                throw error;
+            }
+            return {
+                ...this.projectBinding(record, devices),
+                deviceName: typeof attachment.deviceName === "string"
+                    ? attachment.deviceName
+                    : record.deviceName,
+                attachedAt: typeof attachment.attachedAt === "string"
+                    ? attachment.attachedAt
+                    : record.attachedAt,
+                deviceState: "booted",
+                available: true,
+            };
+        });
+    }
+    async detach(input) {
+        return this.serial(input.sessionId, async () => {
+            await this.requireSession(input.sessionId);
+            const record = await this.requireBinding(input);
+            return this.withDeviceReservations(input.sessionId, [{
+                    backend: record.backend,
+                    deviceId: record.deviceId,
+                }], async () => {
+                if (!await this.options.store.release(input.sessionId, input.bindingId)) {
+                    throw new SessionEmulatorServiceError("binding_mismatch", "Emulator binding no longer matches this Session");
+                }
+                return { released: true };
+            });
+        });
+    }
+    async tap(input) {
+        return this.withBinding(input, (record) => this.options.emulator.tap({
+            x: input.x,
+            y: input.y,
+            device: record.deviceId,
+        }));
+    }
+    async type(input) {
+        return this.withBinding(input, (record) => this.options.emulator.type({
+            text: input.text,
+            device: record.deviceId,
+            ...(input.mode === undefined ? {} : { mode: input.mode }),
+        }));
+    }
+    async button(input) {
+        return this.withBinding(input, (record) => this.options.emulator.button({
+            device: record.deviceId,
+            ...(input.name === undefined ? {} : { name: input.name }),
+        }));
+    }
+    async rotate(input) {
+        return this.withBinding(input, (record) => this.options.emulator.rotate({
+            orientation: input.orientation,
+            device: record.deviceId,
+        }));
+    }
+    async launch(input) {
+        return this.withBinding(input, (record) => this.options.emulator.launch({
+            appId: input.appId,
+            device: record.deviceId,
+        }));
+    }
+    async gesture(input) {
+        return this.withBinding(input, (record) => this.options.emulator.gesture({
+            points: input.points,
+            device: record.deviceId,
+        }));
+    }
+    async frame(input) {
+        return this.withBinding(input, async (record) => {
+            if (!this.options.emulator.frame) {
+                throw new SessionEmulatorServiceError("emulator_unavailable", "Emulator presentation is unavailable on this Runtime");
+            }
+            const frame = await this.options.emulator.frame({ device: record.deviceId });
+            if (frame.backend !== record.backend || frame.device !== record.deviceId) {
+                throw new SessionEmulatorServiceError("emulator_unavailable", "Emulator host returned a frame for a different device");
+            }
+            return frame;
+        });
+    }
+    async openSurface(input) {
+        const opened = await this.withBinding(input, async (record) => {
+            let imageStream;
+            let liveTouch;
+            try {
+                input.signal?.throwIfAborted();
+                if (record.backend === "ios" && this.options.emulator.imageStream) {
+                    imageStream = await this.options.emulator.imageStream({
+                        device: record.deviceId,
+                        ...(input.signal ? { signal: input.signal } : {}),
+                    });
+                    if (imageStream.backend !== record.backend || imageStream.device !== record.deviceId) {
+                        throw new Error("Emulator image stream belongs to a different device");
+                    }
+                }
+                if (this.options.emulator.liveTouch) {
+                    liveTouch = await this.options.emulator.liveTouch({
+                        device: record.deviceId,
+                        ...(input.signal ? { signal: input.signal } : {}),
+                    });
+                    if (liveTouch.backend !== record.backend || liveTouch.device !== record.deviceId) {
+                        throw new Error("Emulator touch stream belongs to a different device");
+                    }
+                }
+                input.signal?.throwIfAborted();
+                return { record, imageStream, liveTouch };
+            }
+            catch (error) {
+                imageStream?.close();
+                liveTouch?.close();
+                throw new SessionEmulatorServiceError("emulator_unavailable", "Emulator live Surface could not be opened", { cause: error });
+            }
+        });
+        let closed = false;
+        const assertOpen = () => {
+            if (closed)
+                throw new SessionEmulatorServiceError("emulator_unavailable", "Emulator Surface is closed");
+        };
+        return {
+            sessionId: input.sessionId,
+            bindingId: input.bindingId,
+            backend: opened.record.backend,
+            deviceId: opened.record.deviceId,
+            format: opened.imageStream ? "jpeg" : "png",
+            capture: async () => {
+                assertOpen();
+                await this.withBinding(input, async () => undefined);
+                const bytes = opened.imageStream
+                    ? await opened.imageStream.nextFrame()
+                    : (await this.frame(input)).data;
+                assertOpen();
+                await this.withBinding(input, async () => undefined);
+                return bytes;
+            },
+            touch: async (point) => {
+                assertOpen();
+                await this.withBinding(input, async () => {
+                    if (!opened.liveTouch) {
+                        throw new SessionEmulatorServiceError("emulator_unavailable", "Emulator live touch is unavailable on this Runtime");
+                    }
+                    opened.liveTouch.send(point);
+                });
+            },
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                opened.imageStream?.close();
+                opened.liveTouch?.close();
+            },
+        };
+    }
+    async cleanupSession(sessionId) {
+        await this.serial(sessionId, async () => {
+            const record = await this.options.store.get(sessionId);
+            if (!record) {
+                await this.options.store.releaseSession(sessionId);
+                return;
+            }
+            await this.withDeviceReservations(sessionId, [{
+                    backend: record.backend,
+                    deviceId: record.deviceId,
+                }], async () => {
+                await this.options.store.releaseSession(sessionId);
+            });
+        });
+    }
+    async releaseDevice(backend, deviceId) {
+        await this.withDeviceReservations("device-lifecycle", [{ backend, deviceId }], async () => {
+            await this.options.store.releaseDevice(backend, deviceId);
+        });
+    }
+    /** Serialize destructive device lifecycle commands with Session attachment. */
+    async stopDevice(input) {
+        const devices = await this.devices();
+        const exactIdCandidates = input.device
+            ? devices.filter((device) => device.id === input.device)
+            : [];
+        const exactNameCandidates = input.device
+            ? devices.filter((device) => device.name === input.device)
+            : [];
+        let candidates = exactIdCandidates.length > 0
+            ? exactIdCandidates
+            : exactNameCandidates.length === 1
+                ? exactNameCandidates
+                : [];
+        if (candidates.length === 0) {
+            const session = input.device && this.options.emulator.deviceSession
+                ? await this.options.emulator.deviceSession({ device: input.device })
+                : !input.device
+                    ? await this.options.emulator.active()
+                    : null;
+            const identity = emulatorSessionIdentity(session);
+            if (identity) {
+                const identityIds = devices.filter((device) => device.backend === identity.backend && device.id === identity.deviceId);
+                const identityNames = devices.filter((device) => device.backend === identity.backend &&
+                    (device.id === identity.deviceName || device.name === identity.deviceName));
+                candidates = identityIds.length > 0
+                    ? identityIds
+                    : identityNames.length === 1
+                        ? identityNames
+                        : [];
+            }
+        }
+        return this.withDeviceReservations("device-lifecycle", candidates.map((device) => ({
+            backend: device.backend,
+            deviceId: device.id,
+        })), async () => {
+            const result = input.action === "kill"
+                ? await this.options.emulator.kill({ device: input.device })
+                : await this.options.emulator.shutdown({ device: input.device });
+            if (result && typeof result === "object") {
+                const value = result;
+                if (value.ok === true &&
+                    (value.backend === "ios" || value.backend === "android") &&
+                    typeof value.device === "string") {
+                    await this.options.store.releaseDevice(value.backend, value.device);
+                    for (const candidate of candidates) {
+                        if (candidate.backend === value.backend && candidate.id !== value.device) {
+                            await this.options.store.releaseDevice(candidate.backend, candidate.id);
+                        }
+                    }
+                }
+            }
+            return result;
+        });
+    }
+    async withBinding(input, operation) {
+        return this.serial(input.sessionId, async () => {
+            const record = await this.requireBinding(input);
+            return await this.withDeviceReservations(input.sessionId, [{
+                    backend: record.backend,
+                    deviceId: record.deviceId,
+                }], () => operation(record));
+        });
+    }
+    async serial(sessionId, operation) {
+        const previous = this.sessionOperations.get(sessionId) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => { release = resolve; });
+        this.sessionOperations.set(sessionId, current);
+        await previous.catch(() => undefined);
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+            if (this.sessionOperations.get(sessionId) === current)
+                this.sessionOperations.delete(sessionId);
+        }
+    }
+    async withDeviceReservations(sessionId, devices, operation) {
+        const keys = [...new Set(devices.map((device) => deviceKey(device.backend, device.deviceId)))].sort();
+        const releases = [];
+        try {
+            for (const key of keys)
+                releases.push(await this.acquireDevice(key));
+            for (const key of keys)
+                this.deviceReservations.set(key, sessionId);
+            return await operation();
+        }
+        finally {
+            for (const key of keys) {
+                if (this.deviceReservations.get(key) === sessionId)
+                    this.deviceReservations.delete(key);
+            }
+            for (const release of releases.reverse())
+                release();
+        }
+    }
+    async acquireDevice(key) {
+        const previous = this.deviceOperations.get(key) ?? Promise.resolve();
+        let unlock;
+        const current = new Promise((resolve) => { unlock = resolve; });
+        this.deviceOperations.set(key, current);
+        await previous.catch(() => undefined);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            unlock();
+            if (this.deviceOperations.get(key) === current)
+                this.deviceOperations.delete(key);
+        };
+    }
+    async requireBinding(input) {
+        await this.requireSession(input.sessionId);
+        const record = await this.options.store.get(input.sessionId);
+        if (!record || record.bindingId !== input.bindingId) {
+            throw new SessionEmulatorServiceError("binding_mismatch", "Emulator binding no longer matches this Session");
+        }
+        return record;
+    }
+    async requireSession(sessionId) {
+        if (!await this.options.sessions.exists(sessionId)) {
+            throw new SessionEmulatorServiceError("session_not_found", "Session was not found");
+        }
+    }
+    async devices() {
+        const devices = await this.options.emulator.devices();
+        return devices.filter(isRemoteRuntimeEmulatorDevice);
+    }
+    projectBinding(record, devices) {
+        const device = devices.find((candidate) => candidate.backend === record.backend && candidate.id === record.deviceId);
+        return {
+            sessionId: record.sessionId,
+            bindingId: record.bindingId,
+            backend: record.backend,
+            deviceId: record.deviceId,
+            ...(record.deviceName ? { deviceName: record.deviceName } : {}),
+            deviceState: device?.state ?? "unknown",
+            available: Boolean(device && device.isAvailable !== false),
+            attachedAt: record.attachedAt,
+        };
+    }
+}
+function isRemoteRuntimeEmulatorDevice(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const device = value;
+    return (device.backend === "ios" || device.backend === "android") &&
+        typeof device.id === "string" &&
+        typeof device.name === "string" &&
+        isDeviceState(device.state);
+}
+function isDeviceState(value) {
+    return value === "booted" || value === "shutdown" || value === "unknown";
+}
+function deviceKey(backend, deviceId) {
+    return JSON.stringify([backend, deviceId]);
+}
+function emulatorSessionIdentity(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const session = value;
+    if ((session.backend !== "ios" && session.backend !== "android") ||
+        typeof session.deviceUdid !== "string")
+        return null;
+    return {
+        backend: session.backend,
+        deviceId: session.deviceUdid,
+        ...(typeof session.deviceName === "string" ? { deviceName: session.deviceName } : {}),
+    };
+}

package/dist/session-runtime-index.d.ts

@@ -0,0 +1,23 @@
+import type { SessionEvent } from "@rynx-ai/protocol";
+import type { ControlSessionRuntimeSnapshot } from "@rynx-ai/protocol/control";
+export type SessionRuntimeSnapshot = ControlSessionRuntimeSnapshot;
+export interface SessionRuntimeActivitySnapshot {
+    runningTurns: number;
+    pendingInteractions: number;
+}
+/**
+ * Process-local index of live Session state. Durable transcript items explain
+ * history; this index says which historical requests still have a real runtime
+ * waiter after a client reconnect. It intentionally starts empty after daemon
+ * restart because an old runner waiter cannot be resumed implicitly.
+ */
+export declare class SessionRuntimeIndex {
+    private readonly sessions;
+    observe(sessionId: string, event: SessionEvent): void;
+    snapshot(sessionId: string): SessionRuntimeSnapshot;
+    /** Aggregate only process-live work; durable Session history is not activity. */
+    activitySnapshot(): SessionRuntimeActivitySnapshot;
+    remove(sessionId: string): void;
+    private state;
+    private removeResponseInteractions;
+}