@elizaos/app-core 2.0.0-alpha.85 → 2.0.0-beta.2

package/runtime/mobile-safe-runtime.d.ts

@@ -0,0 +1,123 @@
+export type MobileSafeRuntimePlatform = "ios" | "android" | "web" | "unknown";
+export type MobileSafeRuntimeProviderKind = "javascriptcore" | "quickjs" | "wasm" | "android-isolated-process";
+export type MobileSafeRuntimeCapability = "fs.read" | "fs.write" | "fs.delete" | "net.fetch" | "crypto.random" | "model.inference" | (string & {});
+export interface MobileSafeRuntimeFeatureProbe {
+    env?: Record<string, string | undefined>;
+    globals?: Record<string, unknown>;
+    platform?: MobileSafeRuntimePlatform;
+}
+export interface MobileSafeRuntimeFeatures {
+    platform: MobileSafeRuntimePlatform;
+    supportsWebAssembly: boolean;
+    supportsDynamicImport: boolean;
+    supportsSharedArrayBuffer: boolean;
+    hasNodeRuntime: boolean;
+    hasBunRuntime: boolean;
+    availableProviders: MobileSafeRuntimeProviderKind[];
+    unavailableProviders: Partial<Record<MobileSafeRuntimeProviderKind, string>>;
+}
+export interface MobileSafeRuntimeFileInfo {
+    path: string;
+    kind: "file" | "directory";
+    size: number;
+    updatedAt?: number;
+}
+export interface MobileSafeVirtualFileSystem {
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array): Promise<void>;
+    delete(path: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    stat(path: string): Promise<MobileSafeRuntimeFileInfo | null>;
+    list(path: string): Promise<MobileSafeRuntimeFileInfo[]>;
+}
+export interface MobileSafeRuntimeCapabilityRequest<TArgs extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    capability: MobileSafeRuntimeCapability;
+    operation: string;
+    args: TArgs;
+    subject?: string;
+    timeoutMs?: number;
+}
+export type MobileSafeRuntimeCapabilityResponse<TResult = unknown> = {
+    id: string;
+    ok: true;
+    result: TResult;
+} | {
+    id: string;
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        retryable?: boolean;
+    };
+};
+export interface MobileSafeCapabilityBroker {
+    call<TResult = unknown>(request: MobileSafeRuntimeCapabilityRequest): Promise<MobileSafeRuntimeCapabilityResponse<TResult>>;
+}
+export interface MobileSafeRuntimeExecuteInput {
+    code: string;
+    entrypoint?: string;
+    env?: Record<string, string>;
+    files?: MobileSafeVirtualFileSystem;
+    broker?: MobileSafeCapabilityBroker;
+    signal?: AbortSignal;
+}
+export type MobileSafeRuntimeExecuteResult = {
+    ok: true;
+    value: unknown;
+    logs?: string[];
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        provider: MobileSafeRuntimeProviderKind;
+    };
+    logs?: string[];
+};
+export interface MobileSafeRuntimeProvider {
+    kind: MobileSafeRuntimeProviderKind;
+    displayName: string;
+    supported: boolean;
+    reason?: string;
+    execute(input: MobileSafeRuntimeExecuteInput): Promise<MobileSafeRuntimeExecuteResult>;
+}
+export interface IosJavaScriptCoreBoundary {
+    kind: "javascriptcore";
+    evaluateScript(script: string): Promise<unknown>;
+}
+export interface IosQuickJsBoundary {
+    kind: "quickjs";
+    evaluateModule(moduleSource: string, entrypoint?: string): Promise<unknown>;
+}
+export interface AndroidIsolatedProcessBoundary {
+    kind: "android-isolated-process";
+    serviceName: string;
+    request(request: MobileSafeRuntimeCapabilityRequest): Promise<MobileSafeRuntimeCapabilityResponse>;
+}
+export interface AndroidIsolatedProcessHook {
+    serviceName: string;
+    intentAction: string;
+    binderInterface: string;
+    requiredPermission?: string;
+    processName?: string;
+}
+export declare function detectMobileSafeRuntimeFeatures(probe?: MobileSafeRuntimeFeatureProbe): MobileSafeRuntimeFeatures;
+export declare function createUnavailableMobileSafeRuntimeProvider(kind: MobileSafeRuntimeProviderKind, reason: string): MobileSafeRuntimeProvider;
+export declare function createIosJavaScriptCoreProvider(boundary?: IosJavaScriptCoreBoundary): MobileSafeRuntimeProvider;
+export declare function createIosQuickJsProvider(boundary?: IosQuickJsBoundary): MobileSafeRuntimeProvider;
+export declare function createAndroidIsolatedProcessHook(options?: Partial<AndroidIsolatedProcessHook>): AndroidIsolatedProcessHook;
+export declare function createAndroidIsolatedProcessProvider(boundary?: AndroidIsolatedProcessBoundary): MobileSafeRuntimeProvider;
+export declare function createMobileSafeCapabilityBroker(handler: (request: MobileSafeRuntimeCapabilityRequest) => Promise<MobileSafeRuntimeCapabilityResponse> | MobileSafeRuntimeCapabilityResponse): MobileSafeCapabilityBroker;
+export declare function normalizeMobileSafePath(path: string): string;
+export declare class MemoryMobileSafeVirtualFileSystem implements MobileSafeVirtualFileSystem {
+    private readonly files;
+    private readonly directories;
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array): Promise<void>;
+    delete(path: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    stat(path: string): Promise<MobileSafeRuntimeFileInfo | null>;
+    list(path: string): Promise<MobileSafeRuntimeFileInfo[]>;
+}
+//# sourceMappingURL=mobile-safe-runtime.d.ts.map

package/runtime/mobile-safe-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mobile-safe-runtime.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/mobile-safe-runtime.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,yBAAyB,GAAG,KAAK,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,CAAC;AAE9E,MAAM,MAAM,6BAA6B,GACrC,gBAAgB,GAChB,SAAS,GACT,MAAM,GACN,0BAA0B,CAAC;AAE/B,MAAM,MAAM,2BAA2B,GACnC,SAAS,GACT,UAAU,GACV,WAAW,GACX,WAAW,GACX,eAAe,GACf,iBAAiB,GACjB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,MAAM,WAAW,6BAA6B;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,QAAQ,CAAC,EAAE,yBAAyB,CAAC;CACtC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,yBAAyB,CAAC;IACpC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,yBAAyB,EAAE,OAAO,CAAC;IACnC,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;IACvB,kBAAkB,EAAE,6BAA6B,EAAE,CAAC;IACpD,oBAAoB,EAAE,OAAO,CAAC,MAAM,CAAC,6BAA6B,EAAE,MAAM,CAAC,CAAC,CAAC;CAC9E;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAC;IAC9D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,EAAE,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,kCAAkC,CACjD,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAE/D,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,2BAA2B,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,KAAK,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,mCAAmC,CAAC,OAAO,GAAG,OAAO,IAC7D;IACE,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE,OAAO,CAAC;CACjB,GACD;IACE,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;CACH,CAAC;AAEN,MAAM,WAAW,0BAA0B;IACzC,IAAI,CAAC,OAAO,GAAG,OAAO,EACpB,OAAO,EAAE,kCAAkC,GAC1C,OAAO,CAAC,mCAAmC,CAAC,OAAO,CAAC,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,KAAK,CAAC,EAAE,2BAA2B,CAAC;IACpC,MAAM,CAAC,EAAE,0BAA0B,CAAC;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,MAAM,8BAA8B,GACtC;IACE,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,6BAA6B,CAAC;KACzC,CAAC;IACF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEN,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,6BAA6B,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CACL,KAAK,EAAE,6BAA6B,GACnC,OAAO,CAAC,8BAA8B,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,gBAAgB,CAAC;IACvB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,SAAS,CAAC;IAChB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7E;AAED,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,0BAA0B,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CACL,OAAO,EAAE,kCAAkC,GAC1C,OAAO,CAAC,mCAAmC,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,+BAA+B,CAC7C,KAAK,GAAE,6BAAkC,GACxC,yBAAyB,CAqD3B;AAED,wBAAgB,0CAA0C,CACxD,IAAI,EAAE,6BAA6B,EACnC,MAAM,EAAE,MAAM,GACb,yBAAyB,CAiB3B;AAED,wBAAgB,+BAA+B,CAC7C,QAAQ,CAAC,EAAE,yBAAyB,GACnC,yBAAyB,CAoB3B;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,CAAC,EAAE,kBAAkB,GAC5B,yBAAyB,CAuB3B;AAED,wBAAgB,gCAAgC,CAC9C,OAAO,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAChD,0BAA0B,CAa5B;AAED,wBAAgB,oCAAoC,CAClD,QAAQ,CAAC,EAAE,8BAA8B,GACxC,yBAAyB,CAmC3B;AAED,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,CACP,OAAO,EAAE,kCAAkC,KAEzC,OAAO,CAAC,mCAAmC,CAAC,GAC5C,mCAAmC,GACtC,0BAA0B,CAmB5B;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAY5D;AAED,qBAAa,iCACX,YAAW,2BAA2B;IAEtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAGlB;IACJ,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;IAEhD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAM3C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IASxD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IAiB7D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,EAAE,CAAC;CAuB/D"}

package/runtime/mobile-safe-runtime.js

@@ -0,0 +1,290 @@
+export function detectMobileSafeRuntimeFeatures(probe = {}) {
+    const globals = probe.globals ?? globalThisAsRecord();
+    const env = probe.env ?? {};
+    const platform = resolveMobileSafeRuntimePlatform(probe.platform, env, globals);
+    const supportsWebAssembly = typeof globals.WebAssembly === "object";
+    const supportsDynamicImport = env.ELIZA_MOBILE_DYNAMIC_IMPORT === "1";
+    const supportsSharedArrayBuffer = typeof globals.SharedArrayBuffer === "function";
+    const hasNodeRuntime = typeof globals.process === "object";
+    const hasBunRuntime = typeof globals.Bun === "object";
+    const unavailableProviders = {};
+    const availableProviders = [];
+    if (platform === "ios") {
+        availableProviders.push("javascriptcore", "quickjs");
+    }
+    else {
+        unavailableProviders.javascriptcore =
+            "JavaScriptCore host boundary is only available in the iOS app shell";
+        unavailableProviders.quickjs =
+            "QuickJS host boundary is only available in the iOS app shell";
+    }
+    if (platform === "android") {
+        availableProviders.push("android-isolated-process");
+    }
+    else {
+        unavailableProviders["android-isolated-process"] =
+            "Android isolated-process boundary is only available in the Android app shell";
+    }
+    if (supportsWebAssembly) {
+        availableProviders.push("wasm");
+    }
+    else {
+        unavailableProviders.wasm =
+            "WebAssembly is not exposed by this host runtime";
+    }
+    return {
+        platform,
+        supportsWebAssembly,
+        supportsDynamicImport,
+        supportsSharedArrayBuffer,
+        hasNodeRuntime,
+        hasBunRuntime,
+        availableProviders,
+        unavailableProviders,
+    };
+}
+export function createUnavailableMobileSafeRuntimeProvider(kind, reason) {
+    return {
+        kind,
+        displayName: displayNameForProvider(kind),
+        supported: false,
+        reason,
+        async execute() {
+            return {
+                ok: false,
+                error: {
+                    code: "MOBILE_SAFE_RUNTIME_PROVIDER_UNAVAILABLE",
+                    message: reason,
+                    provider: kind,
+                },
+            };
+        },
+    };
+}
+export function createIosJavaScriptCoreProvider(boundary) {
+    if (!boundary) {
+        return createUnavailableMobileSafeRuntimeProvider("javascriptcore", "iOS JavaScriptCore boundary is not attached; this contract does not imply Bun or Node on iOS");
+    }
+    return {
+        kind: "javascriptcore",
+        displayName: "iOS JavaScriptCore",
+        supported: true,
+        async execute(input) {
+            try {
+                return { ok: true, value: await boundary.evaluateScript(input.code) };
+            }
+            catch (error) {
+                return providerFailure("javascriptcore", error);
+            }
+        },
+    };
+}
+export function createIosQuickJsProvider(boundary) {
+    if (!boundary) {
+        return createUnavailableMobileSafeRuntimeProvider("quickjs", "iOS QuickJS boundary is not attached; this is a native embedder hook, not a Node/Bun runtime");
+    }
+    return {
+        kind: "quickjs",
+        displayName: "iOS QuickJS",
+        supported: true,
+        async execute(input) {
+            try {
+                return {
+                    ok: true,
+                    value: await boundary.evaluateModule(input.code, input.entrypoint),
+                };
+            }
+            catch (error) {
+                return providerFailure("quickjs", error);
+            }
+        },
+    };
+}
+export function createAndroidIsolatedProcessHook(options = {}) {
+    return {
+        serviceName: options.serviceName ?? "ai.elizaos.app.MobileSafeRuntimeService",
+        intentAction: options.intentAction ?? "ai.elizaos.app.action.MOBILE_SAFE_RUNTIME",
+        binderInterface: options.binderInterface ?? "ai.elizaos.app.IMobileSafeRuntime",
+        requiredPermission: options.requiredPermission ??
+            "ai.elizaos.app.permission.MOBILE_SAFE_RUNTIME",
+        processName: options.processName ?? ":eliza_mobile_safe_runtime",
+    };
+}
+export function createAndroidIsolatedProcessProvider(boundary) {
+    if (!boundary) {
+        return createUnavailableMobileSafeRuntimeProvider("android-isolated-process", "Android isolated-process boundary is not attached");
+    }
+    return {
+        kind: "android-isolated-process",
+        displayName: "Android isolated process",
+        supported: true,
+        async execute(input) {
+            const response = await boundary.request({
+                id: cryptoRequestId(),
+                capability: "model.inference",
+                operation: "execute",
+                args: {
+                    code: input.code,
+                    entrypoint: input.entrypoint,
+                    env: input.env ?? {},
+                },
+            });
+            if (response.ok)
+                return { ok: true, value: response.result };
+            return {
+                ok: false,
+                error: {
+                    code: response.error.code,
+                    message: response.error.message,
+                    provider: "android-isolated-process",
+                },
+            };
+        },
+    };
+}
+export function createMobileSafeCapabilityBroker(handler) {
+    return {
+        async call(request) {
+            try {
+                const response = await handler(request);
+                return response;
+            }
+            catch (error) {
+                return {
+                    id: request.id,
+                    ok: false,
+                    error: {
+                        code: "MOBILE_SAFE_CAPABILITY_FAILED",
+                        message: error instanceof Error ? error.message : String(error),
+                        retryable: false,
+                    },
+                };
+            }
+        },
+    };
+}
+export function normalizeMobileSafePath(path) {
+    const normalized = path
+        .replaceAll("\\", "/")
+        .split("/")
+        .filter((part) => part.length > 0 && part !== ".")
+        .reduce((parts, part) => {
+        if (part === "..")
+            parts.pop();
+        else
+            parts.push(part);
+        return parts;
+    }, []);
+    return `/${normalized.join("/")}`;
+}
+export class MemoryMobileSafeVirtualFileSystem {
+    files = new Map();
+    directories = new Set(["/"]);
+    async readFile(path) {
+        const entry = this.files.get(normalizeMobileSafePath(path));
+        if (!entry)
+            throw new Error(`File not found: ${path}`);
+        return new Uint8Array(entry.data);
+    }
+    async writeFile(path, data) {
+        const normalized = normalizeMobileSafePath(path);
+        this.directories.add(parentPath(normalized));
+        this.files.set(normalized, {
+            data: new Uint8Array(data),
+            updatedAt: Date.now(),
+        });
+    }
+    async delete(path) {
+        const normalized = normalizeMobileSafePath(path);
+        this.files.delete(normalized);
+        this.directories.delete(normalized);
+    }
+    async mkdir(path) {
+        this.directories.add(normalizeMobileSafePath(path));
+    }
+    async stat(path) {
+        const normalized = normalizeMobileSafePath(path);
+        const file = this.files.get(normalized);
+        if (file) {
+            return {
+                path: normalized,
+                kind: "file",
+                size: file.data.byteLength,
+                updatedAt: file.updatedAt,
+            };
+        }
+        if (this.directories.has(normalized)) {
+            return { path: normalized, kind: "directory", size: 0 };
+        }
+        return null;
+    }
+    async list(path) {
+        const normalized = normalizeMobileSafePath(path);
+        const entries = [];
+        for (const [filePath, file] of this.files) {
+            if (parentPath(filePath) === normalized) {
+                entries.push({
+                    path: filePath,
+                    kind: "file",
+                    size: file.data.byteLength,
+                    updatedAt: file.updatedAt,
+                });
+            }
+        }
+        for (const directory of this.directories) {
+            if (directory !== normalized && parentPath(directory) === normalized) {
+                entries.push({ path: directory, kind: "directory", size: 0 });
+            }
+        }
+        return entries.sort((left, right) => left.path.localeCompare(right.path));
+    }
+}
+function resolveMobileSafeRuntimePlatform(explicit, env, globals) {
+    if (explicit)
+        return explicit;
+    const envPlatform = env.ELIZA_PLATFORM?.toLowerCase();
+    if (envPlatform === "ios" || envPlatform === "android")
+        return envPlatform;
+    if (typeof globals.Capacitor === "object" && globals.Capacitor !== null) {
+        const capacitor = globals.Capacitor;
+        const platform = capacitor.getPlatform?.();
+        if (platform === "ios" || platform === "android" || platform === "web") {
+            return platform;
+        }
+    }
+    return "unknown";
+}
+function displayNameForProvider(kind) {
+    switch (kind) {
+        case "android-isolated-process":
+            return "Android isolated process";
+        case "javascriptcore":
+            return "iOS JavaScriptCore";
+        case "quickjs":
+            return "iOS QuickJS";
+        case "wasm":
+            return "WebAssembly";
+    }
+}
+function providerFailure(provider, error) {
+    return {
+        ok: false,
+        error: {
+            code: "MOBILE_SAFE_RUNTIME_EXECUTE_FAILED",
+            message: error instanceof Error ? error.message : String(error),
+            provider,
+        },
+    };
+}
+function globalThisAsRecord() {
+    return globalThis;
+}
+function parentPath(path) {
+    const normalized = normalizeMobileSafePath(path);
+    const index = normalized.lastIndexOf("/");
+    return index <= 0 ? "/" : normalized.slice(0, index);
+}
+function cryptoRequestId() {
+    const cryptoGlobal = globalThis.crypto;
+    return cryptoGlobal?.randomUUID?.() ?? `mobile-safe-${Date.now()}`;
+}

package/runtime/mode/remote-forwarder.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Remote-mode forwarder.
+ *
+ * AGENTS.md §1: in `remote` mode, mutating cloud settings must affect the
+ * *target's* cloud settings (the local instance the controller is wired
+ * to), not the controller's own config. The controller has no cloud
+ * surface of its own — every cloud-routed write proxies to the target.
+ *
+ * Reads stay local: the dashboard reads its own status (which is the
+ * thin-client target shape), and queries that need target state already
+ * route through `/api/cloud/v1/*` (the cloud thin-client proxy).
+ *
+ * This module does not catch transport errors — a broken target is a
+ * 502 surface to the caller, not a silent log-and-continue.
+ */
+import type http from "node:http";
+export declare function shouldForwardToRemoteTarget(pathname: string, method: string): boolean;
+/**
+ * Build the outbound `Headers` for the target. Visible for testing.
+ *
+ * Per RFC 7230 §3.2.2, multi-valued request headers (`Cookie`, `Accept`,
+ * `Forwarded`, etc.) are equivalent to a single comma-joined value.
+ * Node parses `set-cookie` and any duplicated header as `string[]`;
+ * we forward every value via `headers.append(name, v)` instead of
+ * silently dropping the array (the previous behavior).
+ */
+export declare function buildForwardHeaders(incoming: http.IncomingHttpHeaders, targetHost: string, remoteAccessToken: string | null): Headers;
+/**
+ * Returns true when the controller forwarded the request to the target
+ * (and wrote the response). Returns false when not in remote mode or the
+ * route is not in the forwarded list, in which case the caller continues
+ * dispatch.
+ */
+export declare function forwardRemoteCloudMutation(req: http.IncomingMessage, res: http.ServerResponse): Promise<boolean>;
+//# sourceMappingURL=remote-forwarder.d.ts.map

package/runtime/mode/remote-forwarder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-forwarder.d.ts","sourceRoot":"","sources":["../../../../../../src/runtime/mode/remote-forwarder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAelC,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAKT;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,IAAI,CAAC,mBAAmB,EAClC,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAC/B,OAAO,CAkBT;AAUD;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,GACvB,OAAO,CAAC,OAAO,CAAC,CAkDlB"}

package/runtime/mode/remote-forwarder.js

@@ -0,0 +1,119 @@
+/**
+ * Remote-mode forwarder.
+ *
+ * AGENTS.md §1: in `remote` mode, mutating cloud settings must affect the
+ * *target's* cloud settings (the local instance the controller is wired
+ * to), not the controller's own config. The controller has no cloud
+ * surface of its own — every cloud-routed write proxies to the target.
+ *
+ * Reads stay local: the dashboard reads its own status (which is the
+ * thin-client target shape), and queries that need target state already
+ * route through `/api/cloud/v1/*` (the cloud thin-client proxy).
+ *
+ * This module does not catch transport errors — a broken target is a
+ * 502 surface to the caller, not a silent log-and-continue.
+ */
+import { fetchWithTimeoutGuard } from "@elizaos/agent";
+import { sendJsonError } from "../../api/response";
+import { getRuntimeModeSnapshot } from "./runtime-mode";
+/** Pathnames whose mutations belong to the target in remote mode. */
+const REMOTE_FORWARDED_MUTATION_PREFIXES = [
+    "/api/cloud/login",
+    "/api/cloud/disconnect",
+    "/api/cloud/billing/",
+    "/api/cloud/v1/",
+];
+const FORWARDED_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+export function shouldForwardToRemoteTarget(pathname, method) {
+    if (!FORWARDED_METHODS.has(method.toUpperCase()))
+        return false;
+    return REMOTE_FORWARDED_MUTATION_PREFIXES.some((p) => p.endsWith("/") ? pathname.startsWith(p) : pathname === p);
+}
+// Per RFC 7230 §6.1, hop-by-hop headers MUST NOT be forwarded by an
+// intermediary. Re-using an upstream `Connection: keep-alive` or stale
+// `Transfer-Encoding` against the target's connection corrupts framing.
+const HOP_BY_HOP_HEADERS = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+]);
+/**
+ * Build the outbound `Headers` for the target. Visible for testing.
+ *
+ * Per RFC 7230 §3.2.2, multi-valued request headers (`Cookie`, `Accept`,
+ * `Forwarded`, etc.) are equivalent to a single comma-joined value.
+ * Node parses `set-cookie` and any duplicated header as `string[]`;
+ * we forward every value via `headers.append(name, v)` instead of
+ * silently dropping the array (the previous behavior).
+ */
+export function buildForwardHeaders(incoming, targetHost, remoteAccessToken) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(incoming)) {
+        if (value === undefined)
+            continue;
+        if (HOP_BY_HOP_HEADERS.has(name.toLowerCase()))
+            continue;
+        if (Array.isArray(value)) {
+            for (const v of value)
+                headers.append(name, v);
+        }
+        else {
+            headers.set(name, value);
+        }
+    }
+    // Replace the Host header — we are addressing the target now, not the
+    // controller.
+    headers.set("host", targetHost);
+    if (remoteAccessToken) {
+        headers.set("authorization", `Bearer ${remoteAccessToken}`);
+    }
+    return headers;
+}
+async function readRequestBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * Returns true when the controller forwarded the request to the target
+ * (and wrote the response). Returns false when not in remote mode or the
+ * route is not in the forwarded list, in which case the caller continues
+ * dispatch.
+ */
+export async function forwardRemoteCloudMutation(req, res) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const method = (req.method ?? "GET").toUpperCase();
+    const snapshot = getRuntimeModeSnapshot();
+    if (snapshot.mode !== "remote")
+        return false;
+    if (!shouldForwardToRemoteTarget(url.pathname, method))
+        return false;
+    if (!snapshot.remoteApiBase) {
+        sendJsonError(res, snapshot.remoteApiBaseError ? 400 : 503, snapshot.remoteApiBaseError ?? "Remote target not configured");
+        return true;
+    }
+    const targetUrl = new URL(`${url.pathname}${url.search}`, snapshot.remoteApiBase);
+    const rawBody = FORWARDED_METHODS.has(method)
+        ? await readRequestBody(req)
+        : undefined;
+    const body = rawBody && rawBody.length > 0 ? rawBody.toString("utf8") : undefined;
+    const headers = buildForwardHeaders(req.headers, targetUrl.host, snapshot.remoteAccessToken);
+    const upstream = await fetchWithTimeoutGuard(targetUrl.toString(), {
+        method,
+        headers,
+        body,
+    }, 30_000);
+    const responseBody = await upstream.arrayBuffer();
+    res.writeHead(upstream.status, {
+        "content-type": upstream.headers.get("content-type") ?? "application/json",
+    });
+    res.end(Buffer.from(responseBody));
+    return true;
+}

package/runtime/mode/route-mode-guard.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Route-level mode guard.
+ *
+ * Runs BEFORE handler logic. If the active runtime mode is not in the
+ * route's matrix entry, responds with 404 (hidden, not 403 — we do not
+ * want cloud mode to be probeable for local-inference state) and returns
+ * `true` so the dispatcher stops walking handlers.
+ *
+ * No defensive try/catch: a config-load failure is the runtime's problem,
+ * not the gate's.
+ */
+import type http from "node:http";
+import { type RuntimeMode } from "./runtime-mode";
+export interface ModeGateOutcome {
+    /** True when the dispatcher should stop — guard wrote a 404. */
+    handled: boolean;
+    /** The active runtime mode at gate time. */
+    mode: RuntimeMode;
+}
+export declare function applyRouteModeGuard(req: http.IncomingMessage, res: http.ServerResponse): ModeGateOutcome;
+//# sourceMappingURL=route-mode-guard.d.ts.map

package/runtime/mode/route-mode-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-mode-guard.d.ts","sourceRoot":"","sources":["../../../../../../src/runtime/mode/route-mode-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG1E,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,OAAO,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,GACvB,eAAe,CAkBjB"}

package/runtime/mode/route-mode-guard.js

@@ -0,0 +1,30 @@
+/**
+ * Route-level mode guard.
+ *
+ * Runs BEFORE handler logic. If the active runtime mode is not in the
+ * route's matrix entry, responds with 404 (hidden, not 403 — we do not
+ * want cloud mode to be probeable for local-inference state) and returns
+ * `true` so the dispatcher stops walking handlers.
+ *
+ * No defensive try/catch: a config-load failure is the runtime's problem,
+ * not the gate's.
+ */
+import { sendJsonError } from "../../api/response";
+import { getRuntimeModeSnapshot } from "./runtime-mode";
+import { findRouteModeRule } from "./route-mode-matrix";
+export function applyRouteModeGuard(req, res) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const method = (req.method ?? "GET").toUpperCase();
+    const snapshot = getRuntimeModeSnapshot();
+    const rule = findRouteModeRule(url.pathname, method);
+    if (!rule) {
+        return { handled: false, mode: snapshot.mode };
+    }
+    if (rule.modes.includes(snapshot.mode)) {
+        return { handled: false, mode: snapshot.mode };
+    }
+    // Hidden — not forbidden. Don't include the mode or rule reason in the
+    // body; cloud mode must not be able to probe local-inference state.
+    sendJsonError(res, 404, "Not found");
+    return { handled: true, mode: snapshot.mode };
+}