@glassly/engine 0.3.5 → 0.3.6-dev.846

package/build/services/LocalMiniappRuntime.js

@@ -32,7 +32,7 @@ import { useGlassesStore } from "../stores/glasses";
 import { SETTINGS, useSettingsStore } from "../stores/settings";
 import { markTranscriptSourceRecent, useTranscriptionDebugStore } from "../stores/transcriptionDebug";
 import { resolveMapboxRenderToken } from "./MapboxTokenService";
-import { createAnthropicProvider, createGeminiProvider, createOpenAiProvider, } from "@glassly/llm-providers";
+import { createAnthropicProvider, createDeepSeekProvider, createGeminiProvider, createOpenAiProvider, } from "@glassly/llm-providers";
 import { normalizeAiTier, resolveAiTier } from "./AiTierResolution";
 import { decideLlmRoute, localLlmReason } from "./LlmRouting";
 import localLlmModelManager from "./LocalLlmModelManager";
@@ -82,6 +82,7 @@ import { invokeScanQrSeam } from "../runtime/scanQrSeam";
 import { invokeWebLoginSeam } from "../runtime/webLoginSeam";
 import { normalizeStreamAudioConfig, normalizeStreamVideoConfig } from "../runtime/streamConfig";
 import { visibleActionRows } from "./manifestActions";
+import { actionFailure, appDeclaresAction, checkActionAccess, PendingActionCalls, } from "./actionInvoke";
 import { toLanguageHint } from "@glassly/cloud-protocol/languages";
 import { buildMiniappManifestSnapshot } from "../utils/miniappDiagnostics";
 import ttsModelManager from "./TTSModelManager";
@@ -95,6 +96,8 @@ import { listPhoneCalendarEvents, PhoneCalendarError } from "./PhoneCalendarServ
 import { LocalMiniappStorage } from "./LocalMiniappStorage";
 import { captureDecisionFor } from "./MemoryCapture";
 import { memoryStore } from "./memoryStoreInstance";
+import { exportMemoryFile, importMemoryFile } from "./memoryBackupFile";
+import { MemoryBackupError } from "./MemoryStore";
 import { speakerProfileStore } from "./speakerProfileStoreInstance";
 /** Streams that carry speech text and so have a cloud route and an on-device route. */
 const isSpeechTextStream = (stream) => stream.startsWith("transcription:") || stream.startsWith("translation:");
@@ -247,6 +250,7 @@ const MINIAPP_READABLE_API_KEYS = {
     anthropic: SETTINGS.anthropic_api_key.key,
     gemini: SETTINGS.gemini_api_key.key,
     openai: SETTINGS.openai_api_key.key,
+    deepseek: SETTINGS.deepseek_api_key.key,
     elevenlabs: SETTINGS.elevenlabs_api_key.key,
     mapbox: SETTINGS.mapbox_api_key.key,
 };
@@ -267,7 +271,9 @@ function directLlmProvider(name) {
         ? createGeminiProvider({ logger })
         : name === "openai"
             ? createOpenAiProvider({ logger })
-            : createAnthropicProvider({ logger });
+            : name === "deepseek"
+                ? createDeepSeekProvider({ logger })
+                : createAnthropicProvider({ logger });
     directLlmProviders.set(name, built);
     return built;
 }
@@ -283,6 +289,7 @@ function savedLlmKeys() {
         anthropic: userLlmKey("anthropic").length > 0,
         gemini: userLlmKey("gemini").length > 0,
         openai: userLlmKey("openai").length > 0,
+        deepseek: userLlmKey("deepseek").length > 0,
     };
 }
 /** The stored Settings > AI Models dropdown value for a tier ("auto" default). */
@@ -438,6 +445,10 @@ class LocalMiniappRuntime {
     connectedApps = new Map();
     /** Claimed gestures (CLAIM_GESTURES): a stack per gesture, the most recent claimer holding it. */
     gestureClaims = emptyGestureClaims();
+    // The last main-view frame each app asked to render. Widget mode refuses
+    // frames and demotion clears them, and an app that has drawn once may not
+    // draw again on its own, so promotion replays this.
+    retainedRenders = new Map();
     /**
      * Packages that have completed their CONNECT handshake (sent
      * `miniapp_connect`, got `CONNECT_ACK`). Distinct from `connectedApps`,
@@ -490,7 +501,14 @@ class LocalMiniappRuntime {
     // secret never leaves the device.
     localSecret = `miniapp_${Date.now()}_${Math.random().toString(36).slice(2, 14)}`;
     usedTokens = new Set();
-    constructor() { }
+    constructor() {
+        miniappWidgetMode.subscribe((packageName, widgetOnly) => {
+            // Promotion happens inside the apps store's start(); the core-app slot
+            // settles with that store write, so replay once it has.
+            if (!widgetOnly)
+                queueMicrotask(() => this.replayRetainedRender(packageName));
+        });
+    }
     /** Snapshot of miniapps actively subscribed to hardware button events. */
     getButtonPressSubscribers() {
         return [...(this.streamSubscribers.get(MiniappStreamType.BUTTON_PRESS) ?? [])].sort();
@@ -874,7 +892,11 @@ class LocalMiniappRuntime {
         // window ends early once this app pushes its first display (see
         // LocalDisplayManager.request), or after ~1.5s. Fires once per spawn —
         // including a crash-respawn, since each spawn is a fresh "app is starting".
-        localDisplayManager.onMount(packageName, installedManifest?.name ?? packageName);
+        // A spawn for a dashboard widget is not the wearer starting the app: it draws
+        // nothing of its own, so it shows no boot text either.
+        if (!miniappWidgetMode.isWidgetOnly(packageName)) {
+            localDisplayManager.onMount(packageName, installedManifest?.name ?? packageName);
+        }
     }
     /**
      * Resolve once `packageName` has completed its CONNECT handshake. If it has
@@ -996,6 +1018,7 @@ class LocalMiniappRuntime {
         }
         // Its gesture claims go back to whoever claimed them before.
         this.applyGestureClaimChanges(dropGestureClaims(this.gestureClaims, packageName));
+        this.retainedRenders.delete(packageName);
         // Warm-up is a request-owned camera lease. Cancel it even if the app record was already
         // removed so a close racing the camera-open promise cannot leave the sensor running.
         // Keep camera teardown ordered: restoring FOV can restart the HAL, so the warm-up lease must
@@ -1300,6 +1323,8 @@ class LocalMiniappRuntime {
             case MiniappRequestType.MEMORY_QUERY:
             case MiniappRequestType.MEMORY_WINDOW:
             case MiniappRequestType.MEMORY_EXPORT_TEXT:
+            case MiniappRequestType.MEMORY_EXPORT_FILE:
+            case MiniappRequestType.MEMORY_IMPORT_FILE:
             case MiniappRequestType.MEMORY_SUMMARY_ADD:
             case MiniappRequestType.MEMORY_SUMMARY_LIST:
             case MiniappRequestType.MEMORY_PENDING_SUMMARY_HOUR:
@@ -1491,6 +1516,9 @@ class LocalMiniappRuntime {
             case MiniappRequestType.WIDGET_RESULT:
                 this.handleWidgetResult(packageName, payload);
                 break;
+            case MiniappRequestType.WIDGET_EXPANDABLE:
+                this.handleWidgetExpandable(packageName, payload, requestId);
+                break;
             case MiniappRequestType.SYSTEM_EXIT:
                 void this.handleSystemExit(packageName, requestId);
                 break;
@@ -2124,11 +2152,6 @@ class LocalMiniappRuntime {
                 this.sendResult(packageName, requestId, true, { status: "blocked", reason: "app stopped" });
                 return;
             }
-            // A widget-only app draws through its widget alone.
-            if (miniappWidgetMode.isWidgetOnly(packageName)) {
-                this.sendResult(packageName, requestId, true, { status: "blocked", reason: "widget mode" });
-                return;
-            }
             if (!Array.isArray(payload.elements)) {
                 this.sendResult(packageName, requestId, false, undefined, {
                     code: MiniappErrorCode.INTERNAL,
@@ -2136,6 +2159,17 @@ class LocalMiniappRuntime {
                 });
                 return;
             }
+            if (payload.view !== "dashboard") {
+                if (payload.elements.length === 0)
+                    this.retainedRenders.delete(packageName);
+                else
+                    this.retainedRenders.set(packageName, payload);
+            }
+            // A widget-only app draws through its widget alone; the frame waits for promotion.
+            if (miniappWidgetMode.isWidgetOnly(packageName)) {
+                this.sendResult(packageName, requestId, true, { status: "blocked", reason: "widget mode" });
+                return;
+            }
             // The dashboard view is the overlay app's alone; anyone else's frame
             // is dropped, reported rather than silently lost.
             if (payload.view === "dashboard" && !isOverlayApp(packageName)) {
@@ -2160,6 +2194,13 @@ class LocalMiniappRuntime {
             });
         }
     }
+    /** Put a promoted app's last main-view frame on the glasses; widget mode had refused it. */
+    replayRetainedRender(packageName) {
+        const payload = this.retainedRenders.get(packageName);
+        if (!payload || !this.connectedApps.has(packageName) || miniappWidgetMode.isWidgetOnly(packageName))
+            return;
+        this.handleRender(packageName, payload);
+    }
     /**
      * display.showView: the active dashboard takes or releases the overlay
      * slot. Refused (NOT_PERMITTED) for an app that is not a dashboard;
@@ -3433,6 +3474,14 @@ class LocalMiniappRuntime {
                     this.sendResult(packageName, requestId, true, { text: await memoryStore.exportText(scope, num(payload.at)) });
                     return;
                 }
+                case MiniappRequestType.MEMORY_EXPORT_FILE: {
+                    this.sendResult(packageName, requestId, true, await exportMemoryFile());
+                    return;
+                }
+                case MiniappRequestType.MEMORY_IMPORT_FILE: {
+                    this.sendResult(packageName, requestId, true, { imported: await importMemoryFile() });
+                    return;
+                }
                 case MiniappRequestType.MEMORY_SUMMARY_ADD: {
                     const hourStart = num(payload.hourStart);
                     if (hourStart == null || typeof payload.text !== "string") {
@@ -3469,6 +3518,13 @@ class LocalMiniappRuntime {
             }
         }
         catch (err) {
+            if (err instanceof MemoryBackupError) {
+                this.sendResult(packageName, requestId, false, undefined, {
+                    code: MiniappErrorCode.INVALID_ARGUMENT,
+                    message: err.message,
+                });
+                return;
+            }
             console.error(`${LOG_TAG}: ${requestType} error:`, err);
             this.sendResult(packageName, requestId, false, undefined, {
                 code: MiniappErrorCode.INTERNAL,
@@ -3985,7 +4041,7 @@ class LocalMiniappRuntime {
             if (base64) {
                 // File share via base64 — write to temp file then share
                 const tempFile = new File(Paths.cache, filename || "shared_file");
-                tempFile.write(base64, { encoding: "base64" });
+                tempFile.writeSync(base64, { encoding: "base64" });
                 await Share.open({
                     url: tempFile.uri,
                     type: mimeType || "application/octet-stream",
@@ -4055,7 +4111,7 @@ class LocalMiniappRuntime {
             let file;
             if (base64) {
                 file = new File(Paths.cache, name);
-                file.write(base64, { encoding: "base64" });
+                file.writeSync(base64, { encoding: "base64" });
             }
             else if (url) {
                 file = await File.downloadFileAsync(url, new File(Paths.cache, name), { idempotent: true });
@@ -5224,7 +5280,7 @@ class LocalMiniappRuntime {
     /** Max serialized size of an action call's params / result (256 KB). */
     static ACTION_PAYLOAD_CAP = 256 * 1024;
     /** Outstanding action invocations, keyed by host-generated callId. */
-    actionCalls = new Map();
+    actionCalls = new PendingActionCalls(BgTimer, (value) => this.actionPayloadTooLarge(value));
     actionCallSeq = 0;
     interopApps() {
         return useAppStatusStore.getState().apps;
@@ -5238,6 +5294,9 @@ class LocalMiniappRuntime {
         const app = this.interopApps().find((a) => a.packageName === packageName);
         if (!app)
             return false;
+        // Running only for its widget: start() promotes it to a normal run, as opening it on the phone does.
+        if (app.widgetOnly)
+            return useAppStatusStore.getState().start(app, { skipNavigation: true });
         if (app.local) {
             await miniappLauncher.ensureConnected(packageName);
             return true;
@@ -5291,7 +5350,8 @@ class LocalMiniappRuntime {
             packageName: app.packageName,
             name: app.name,
             version: app.version ?? "",
-            running: app.running,
+            // A provider running only for a placed widget is not a run the wearer started.
+            running: app.running && !app.widgetOnly,
             hidden: app.hidden === true,
             system: isSystemMiniapp(app),
             compatibility,
@@ -5463,6 +5523,8 @@ class LocalMiniappRuntime {
     widgetCallSeq = 0;
     /** Elements per widget frame; a card is small, and the link is slow. */
     static WIDGET_FRAME_ELEMENT_CAP = 64;
+    /** Elements per expanded widget frame: the full screen, on the same link. */
+    static WIDGET_EXPANDED_FRAME_ELEMENT_CAP = 128;
     requireWidgetHost(packageName, requestId, op) {
         return this.requirePermission(packageName, requestId, "HOST_WIDGETS", `to ${op} widgets`);
     }
@@ -5505,6 +5567,7 @@ class LocalMiniappRuntime {
                     name: widget.name,
                     sizes: widget.sizes,
                     defaultSize: widget.defaultSize,
+                    expandable: widget.expandOnTap,
                     running: app.running,
                     compatible: app.compatibility?.isCompatible !== false,
                 });
@@ -5516,7 +5579,7 @@ class LocalMiniappRuntime {
         const box = raw;
         if (!box || typeof box !== "object")
             return null;
-        if (box.size !== "XS" && box.size !== "SM" && box.size !== "MD" && box.size !== "LG")
+        if (box.size !== "XS" && box.size !== "XSM" && box.size !== "SM" && box.size !== "MD" && box.size !== "LG")
             return null;
         const width = Number(box.width);
         const height = Number(box.height);
@@ -5538,7 +5601,7 @@ class LocalMiniappRuntime {
     /**
      * session.widgets.place: record the host's box, wake the provider in widget
      * mode when it is not running, hand it the box, and answer with the last
-     * frame the provider pushed for the widget.
+     * card and expanded frames the provider pushed for the widget.
      */
     async handleWidgetPlace(hostPackageName, payload, requestId) {
         if (!this.requireWidgetHost(hostPackageName, requestId, "place"))
@@ -5564,10 +5627,12 @@ class LocalMiniappRuntime {
         }
         const provider = app.packageName;
         // Record the placement before the wake so the spawn lands in widget mode
-        // and an unplace racing it cannot stop the provider early.
+        // and an unplace racing it cannot stop the provider early. A provider the
+        // store already runs (a wearer's launch still spawning, say) stays a
+        // normal run; the registry alone lags that launch.
         this.widgetPlacements = placeWidget(this.widgetPlacements, { hostPackageName, providerPackageName: provider, widgetId, box });
         miniappWidgetMode.setPlaced(provider, true);
-        if (!miniappRunningRegistry.has(provider))
+        if (!app.running && !miniappRunningRegistry.has(provider))
             miniappWidgetMode.setWidgetOnly(provider, true);
         try {
             await this.wakeInteropApp(provider);
@@ -5585,7 +5650,10 @@ class LocalMiniappRuntime {
         if (placementOf(this.widgetPlacements, hostPackageName, provider, widgetId) && this.connectedApps.has(provider)) {
             this.sendWidgetCall(provider, widgetId, { kind: "box", box });
         }
-        this.sendResult(hostPackageName, requestId, true, { frame: widgetFrameOf(this.widgetPlacements, provider, widgetId) });
+        this.sendResult(hostPackageName, requestId, true, {
+            frame: widgetFrameOf(this.widgetPlacements, provider, widgetId),
+            expandedFrame: widgetFrameOf(this.widgetPlacements, provider, widgetId, "expanded"),
+        });
     }
     async handleWidgetUnplace(hostPackageName, payload, requestId) {
         if (!this.requireWidgetHost(hostPackageName, requestId, "unplace"))
@@ -5702,22 +5770,54 @@ class LocalMiniappRuntime {
             this.sendResult(pending.hostPackageName, pending.hostRequestId, false, undefined, error);
         }
     }
-    /** Provider → host, one-shot: cache the frame and push it to every host holding the widget. */
+    /** Provider: read, or set with `expandable`, whether a tap expands one of its own `EX` widgets. */
+    handleWidgetExpandable(packageName, payload, requestId) {
+        const widgetId = payload.widgetId;
+        const app = this.interopApps().find((a) => a.packageName === packageName);
+        const widget = app && widgetId ? this.declaredWidget(app, widgetId) : undefined;
+        if (!widget?.expandable) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.WIDGET_NOT_FOUND,
+                message: `${packageName} has no widget "${widgetId ?? "(missing widgetId)"}" that lists EX`,
+            });
+            return;
+        }
+        const expandable = typeof payload.expandable === "boolean"
+            ? useAppStatusStore.getState().setWidgetExpand(packageName, widget.id, payload.expandable)
+            : widget.expandOnTap;
+        this.sendResult(packageName, requestId, true, { expandable });
+    }
+    /** Provider → host, one-shot: cache the frame for its view and push it to every host holding the widget. */
     handleWidgetUpdate(providerPackageName, payload) {
         const widgetId = payload.widgetId;
         const elements = payload.elements;
         if (!widgetId || !Array.isArray(elements))
             return;
         const app = this.interopApps().find((a) => a.packageName === providerPackageName);
-        if (!app || !this.declaredWidget(app, widgetId))
+        const widget = app ? this.declaredWidget(app, widgetId) : undefined;
+        if (!widget)
             return;
-        if (elements.length > LocalMiniappRuntime.WIDGET_FRAME_ELEMENT_CAP || this.actionPayloadTooLarge(elements)) {
-            console.warn(`${LOG_TAG}: dropping oversized widget frame from ${providerPackageName}/${widgetId}`);
+        const view = payload.view === "expanded" ? "expanded" : "card";
+        if (view === "expanded" && !widget.expandable) {
+            console.warn(`${LOG_TAG}: dropping expanded frame from ${providerPackageName}/${widgetId}: it does not list EX`);
             return;
         }
-        this.widgetPlacements = setWidgetFrame(this.widgetPlacements, providerPackageName, widgetId, elements);
+        const cap = view === "expanded"
+            ? LocalMiniappRuntime.WIDGET_EXPANDED_FRAME_ELEMENT_CAP
+            : LocalMiniappRuntime.WIDGET_FRAME_ELEMENT_CAP;
+        if (elements.length > cap || this.actionPayloadTooLarge(elements)) {
+            console.warn(`${LOG_TAG}: dropping oversized ${view} widget frame from ${providerPackageName}/${widgetId}`);
+            return;
+        }
+        this.widgetPlacements = setWidgetFrame(this.widgetPlacements, providerPackageName, widgetId, elements, view);
         for (const host of widgetHostsOf(this.widgetPlacements, providerPackageName, widgetId)) {
-            this.sendToMiniapp(host, { type: MiniappResponseType.WIDGET_FRAME, packageName: providerPackageName, widgetId, elements });
+            this.sendToMiniapp(host, {
+                type: MiniappResponseType.WIDGET_FRAME,
+                packageName: providerPackageName,
+                widgetId,
+                elements,
+                ...(view === "expanded" ? { view } : {}),
+            });
         }
     }
     /** A miniapp disconnected: as a host its placements go, as a provider its boxes are forgotten and its frames kept. */
@@ -5754,104 +5854,82 @@ class LocalMiniappRuntime {
             return false;
         }
     }
+    /** Floored at 6s: a freshly-woken target buffers an undelivered ACTION_CALL for 5s (HANDLER_WAIT_MS in @glassly/miniapp's actions module) + 1s for the reply. Keep in sync. */
+    static clampActionTimeout(raw) {
+        return Math.min(Math.max(Number(raw) || 30_000, 6_000), 120_000);
+    }
+    /** Caller identity the host presents for host-initiated actions (a system caller). */
+    static HOST_ACTION_CALLER = "host";
+    /** Installed, compatible, and declares the action — the same gates `invokeActionFromHost` applies up front. */
+    hostActionAvailable(targetPackageName, actionId) {
+        return appDeclaresAction(this.interopApps().find((a) => a.packageName === targetPackageName), actionId);
+    }
     /**
-     * session.actions.invoke → wake the target headlessly, deliver an ACTION_CALL,
-     * and correlate its ACTION_RESULT back to the caller's pending request.
+     * Host-initiated action call (e.g. the watch remote): same gates, headless
+     * wake and ACTION_CALL/ACTION_RESULT correlation as a miniapp's
+     * session.actions.invoke, with the host as a system caller.
+     * Rejects with an Error whose `code` is a MiniappErrorCode.
      */
+    async invokeActionFromHost(targetPackageName, actionId, params = {}, timeoutMs) {
+        const outcome = await this.runActionInvoke(LocalMiniappRuntime.HOST_ACTION_CALLER, true, targetPackageName, actionId, params, LocalMiniappRuntime.clampActionTimeout(timeoutMs));
+        if (outcome.ok)
+            return outcome.data;
+        throw Object.assign(new Error(outcome.error.message), { code: outcome.error.code });
+    }
+    /** session.actions.invoke → run the call, then relay the outcome to the caller's pending request. */
     async handleActionInvoke(callerPackageName, payload, requestId) {
-        const target = payload.targetPackageName;
-        const actionId = payload.actionId;
-        const params = payload.params ?? {};
-        // Floor the timeout at 6s so the host never rejects with ACTION_TIMEOUT before
-        // the target SDK's handler-registration window closes. A freshly-woken miniapp
-        // buffers an undelivered ACTION_CALL for HANDLER_WAIT_MS (5s in @glassly/miniapp's
-        // actions module) waiting for session.actions.handle; a shorter host timeout
-        // could fire while the target is still registering, then the action would run
-        // with no caller left to receive its result. 6s = that 5s buffer + 1s for the
-        // ACTION_RESULT/NO_ACTION_HANDLER reply to travel back. Keep these in sync.
-        const timeoutMs = Math.min(Math.max(Number(payload.timeoutMs) || 30_000, 6_000), 120_000);
+        const outcome = await this.runActionInvoke(callerPackageName, this.isSystemPackage(callerPackageName), payload.targetPackageName, payload.actionId, payload.params ?? {}, LocalMiniappRuntime.clampActionTimeout(payload.timeoutMs));
+        if (outcome.ok)
+            this.sendResult(callerPackageName, requestId, true, outcome.data);
+        else
+            this.sendResult(callerPackageName, requestId, false, undefined, outcome.error);
+    }
+    /**
+     * Gate, wake the target headlessly, deliver an ACTION_CALL, and resolve when
+     * its ACTION_RESULT (or the timeout) arrives. Never rejects.
+     */
+    async runActionInvoke(callerPackageName, callerIsSystem, target, actionId, params, timeoutMs) {
+        const fail = actionFailure;
         if (this.actionPayloadTooLarge(params)) {
-            this.sendResult(callerPackageName, requestId, false, undefined, {
-                code: MiniappErrorCode.PAYLOAD_TOO_LARGE,
-                message: "action params exceeded the 256 KB cap",
-            });
-            return;
+            return fail(MiniappErrorCode.PAYLOAD_TOO_LARGE, "action params exceeded the 256 KB cap");
         }
         const app = target ? this.interopApps().find((a) => a.packageName === target) : undefined;
-        if (!target || !app) {
-            this.sendResult(callerPackageName, requestId, false, undefined, {
-                code: MiniappErrorCode.APP_NOT_FOUND,
-                message: `Miniapp not found: ${target ?? "(missing targetPackageName)"}`,
-            });
-            return;
-        }
-        if (!actionId) {
-            this.sendResult(callerPackageName, requestId, false, undefined, {
-                code: MiniappErrorCode.ACTION_NOT_FOUND,
-                message: "invoke requires an actionId",
-            });
-            return;
-        }
-        if (app.compatibility && app.compatibility.isCompatible === false) {
-            this.sendResult(callerPackageName, requestId, false, undefined, {
-                code: MiniappErrorCode.APP_NOT_COMPATIBLE,
-                message: `${target} is not compatible with the connected glasses`,
-            });
-            islandNotifications.emit({
-                kind: "version_incompatible",
-                packageName: target,
-                reason: `${target} is not compatible with the connected glasses`,
-                metadata: { missingRequired: app.compatibility.missingRequired ?? [], via: "miniapps.invoke" },
-                timestamp: Date.now(),
-            });
-            return;
-        }
-        // Declared-action gate: the target must declare the action in its manifest.
-        const declared = (app.actions ?? []).find((a) => a.id === actionId);
-        if (!declared) {
-            this.sendResult(callerPackageName, requestId, false, undefined, {
-                code: MiniappErrorCode.ACTION_NOT_FOUND,
-                message: `${target} does not declare action "${actionId}"`,
-            });
-            return;
-        }
-        // Visibility gate: declared actions are public by default; ones marked
-        // `visibility: "system"` stay restricted to system/dev callers.
-        if (declared.visibility === "system" && !this.isSystemPackage(callerPackageName)) {
-            this.auditInterop({
-                caller: callerPackageName,
-                op: "invoke",
-                target,
-                actionId,
-                ok: false,
-                errorCode: MiniappErrorCode.NOT_PERMITTED,
-            });
-            this.sendResult(callerPackageName, requestId, false, undefined, {
-                code: MiniappErrorCode.NOT_PERMITTED,
-                message: `Action "${actionId}" on ${target} is restricted to system apps`,
-            });
-            return;
+        const denied = checkActionAccess(app, target, actionId, callerIsSystem);
+        if (denied) {
+            if (denied.code === MiniappErrorCode.APP_NOT_COMPATIBLE && target && app) {
+                islandNotifications.emit({
+                    kind: "version_incompatible",
+                    packageName: target,
+                    reason: denied.message,
+                    metadata: { missingRequired: app.compatibility?.missingRequired ?? [], via: "miniapps.invoke" },
+                    timestamp: Date.now(),
+                });
+            }
+            else if (denied.code === MiniappErrorCode.NOT_PERMITTED) {
+                this.auditInterop({
+                    caller: callerPackageName,
+                    op: "invoke",
+                    target,
+                    actionId,
+                    ok: false,
+                    errorCode: MiniappErrorCode.NOT_PERMITTED,
+                });
+            }
+            return { ok: false, error: denied };
         }
+        if (!target || !actionId)
+            return fail(MiniappErrorCode.INTERNAL, "unreachable");
         // Headless wake + wait for CONNECT (idempotent / fast if already connected).
         try {
             await this.wakeInteropApp(target);
         }
         catch (e) {
-            this.sendResult(callerPackageName, requestId, false, undefined, {
-                code: MiniappErrorCode.WAKE_FAILED,
-                message: e?.message ?? `failed to wake ${target}`,
-            });
-            return;
+            return fail(MiniappErrorCode.WAKE_FAILED, e?.message ?? `failed to wake ${target}`);
         }
         // The wake waited for CONNECT, but the target could have dropped in the gap
         // before delivery — fail fast rather than arming a timer for a call that
-        // sendToMiniapp would silently drop (the caller would otherwise wait the
-        // full invoke timeout for an ACTION_CALL that was never delivered).
+        // sendToMiniapp would silently drop.
         if (!this.connectedApps.has(target)) {
-            this.sendResult(callerPackageName, requestId, false, undefined, {
-                code: MiniappErrorCode.WAKE_FAILED,
-                message: `${target} disconnected before the action could be delivered`,
-            });
             this.auditInterop({
                 caller: callerPackageName,
                 op: "invoke",
@@ -5860,18 +5938,11 @@ class LocalMiniappRuntime {
                 ok: false,
                 errorCode: MiniappErrorCode.WAKE_FAILED,
             });
-            return;
+            return fail(MiniappErrorCode.WAKE_FAILED, `${target} disconnected before the action could be delivered`);
         }
-        // Deliver the call and arm the handler timeout; ACTION_RESULT resolves it.
+        // Deliver the call and arm the handler timeout; ACTION_RESULT settles it.
         const callId = `act-${Date.now().toString(36)}-${this.actionCallSeq++}`;
-        const timer = BgTimer.setTimeout(() => {
-            this.actionCalls.delete(callId);
-            this.sendResult(callerPackageName, requestId, false, undefined, {
-                code: MiniappErrorCode.ACTION_TIMEOUT,
-                message: `action "${actionId}" timed out after ${timeoutMs}ms`,
-            });
-        }, timeoutMs);
-        this.actionCalls.set(callId, { callerPackageName, targetPackageName: target, callerRequestId: requestId, timer });
+        const outcome = this.actionCalls.register(callId, target, actionId, timeoutMs);
         this.sendToMiniapp(target, {
             type: MiniappResponseType.ACTION_CALL,
             callId,
@@ -5880,40 +5951,11 @@ class LocalMiniappRuntime {
             callerPackageName,
         });
         this.auditInterop({ caller: callerPackageName, op: "invoke", target, actionId, ok: true });
+        return outcome;
     }
-    /** Target → host: forward an ACTION_RESULT back to the caller's pending invoke. */
+    /** Target → host: settle the pending invoke for this ACTION_RESULT. */
     handleActionResult(targetPackageName, payload) {
-        const callId = payload.callId;
-        if (!callId)
-            return;
-        const pending = this.actionCalls.get(callId);
-        if (!pending)
-            return;
-        // Only the invoked target may resolve this call. callIds are guessable
-        // (timestamp + seq), so a different connected miniapp must not be able to
-        // spoof a result/error for someone else's invoke.
-        if (pending.targetPackageName !== targetPackageName)
-            return;
-        this.actionCalls.delete(callId);
-        BgTimer.clearTimeout(pending.timer);
-        if (payload.ok === true) {
-            const result = payload.result;
-            if (this.actionPayloadTooLarge(result)) {
-                this.sendResult(pending.callerPackageName, pending.callerRequestId, false, undefined, {
-                    code: MiniappErrorCode.PAYLOAD_TOO_LARGE,
-                    message: "action result exceeded the 256 KB cap",
-                });
-                return;
-            }
-            this.sendResult(pending.callerPackageName, pending.callerRequestId, true, result ?? null);
-        }
-        else {
-            const error = payload.error ?? {
-                code: MiniappErrorCode.INTERNAL,
-                message: "action handler error",
-            };
-            this.sendResult(pending.callerPackageName, pending.callerRequestId, false, undefined, error);
-        }
+        this.actionCalls.handleResult(targetPackageName, payload);
     }
     sendResult(packageName, requestId, ok, data, error) {
         if (!requestId)