@glassly/engine 0.3.5 → 0.3.6-beta.851

package/src/services/LocalMiniappRuntime.ts

@@ -46,6 +46,7 @@ import {markTranscriptSourceRecent, useTranscriptionDebugStore} from "../stores/
 import {resolveMapboxRenderToken} from "./MapboxTokenService"
 import {
   createAnthropicProvider,
+  createDeepSeekProvider,
   createGeminiProvider,
   createOpenAiProvider,
   type LlmProviderImpl,
@@ -109,6 +110,7 @@ import {
   unplaceWidget,
   type WidgetBox,
   type WidgetPlacements,
+  type WidgetView,
 } from "./widgetPlacements"
 import {
   activeDashboard,
@@ -162,6 +164,13 @@ 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,
+  type ActionOutcome,
+} from "./actionInvoke"
 import {toLanguageHint} from "@glassly/cloud-protocol/languages"
 import {buildMiniappManifestSnapshot, type MiniappRuntimeDiagnosticSnapshot} from "../utils/miniappDiagnostics"
 import ttsModelManager from "./TTSModelManager"
@@ -176,6 +185,8 @@ import {listPhoneCalendarEvents, PhoneCalendarError} from "./PhoneCalendarServic
 import {LocalMiniappStorage} from "./LocalMiniappStorage"
 import {captureDecisionFor, type CaptureCandidate} from "./MemoryCapture"
 import {memoryStore} from "./memoryStoreInstance"
+import {exportMemoryFile, importMemoryFile} from "./memoryBackupFile"
+import {MemoryBackupError} from "./MemoryStore"
 import {speakerProfileStore} from "./speakerProfileStoreInstance"
 
 // =============================================================================
@@ -419,6 +430,7 @@ const MINIAPP_READABLE_API_KEYS: Record<string, string> = {
   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,
 }
@@ -440,7 +452,9 @@ function directLlmProvider(name: AiTierProvider): LlmProviderImpl {
       ? createGeminiProvider({logger})
       : name === "openai"
         ? createOpenAiProvider({logger})
-        : createAnthropicProvider({logger})
+        : name === "deepseek"
+          ? createDeepSeekProvider({logger})
+          : createAnthropicProvider({logger})
   directLlmProviders.set(name, built)
   return built
 }
@@ -460,6 +474,7 @@ function savedLlmKeys(): SavedLlmKeys {
     anthropic: userLlmKey("anthropic").length > 0,
     gemini: userLlmKey("gemini").length > 0,
     openai: userLlmKey("openai").length > 0,
+    deepseek: userLlmKey("deepseek").length > 0,
   }
 }
 
@@ -641,6 +656,10 @@ class LocalMiniappRuntime {
   private connectedApps: Map<string, ConnectedMiniapp> = new Map()
   /** Claimed gestures (CLAIM_GESTURES): a stack per gesture, the most recent claimer holding it. */
   private gestureClaims: GestureClaimState = 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.
+  private retainedRenders = new Map<string, Record<string, unknown>>()
 
   /**
    * Packages that have completed their CONNECT handshake (sent
@@ -705,7 +724,13 @@ class LocalMiniappRuntime {
   private localSecret = `miniapp_${Date.now()}_${Math.random().toString(36).slice(2, 14)}`
   private usedTokens = new Set<string>()
 
-  private constructor() {}
+  private 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. */
   public getButtonPressSubscribers(): string[] {
@@ -1122,7 +1147,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)
+    }
   }
 
   /**
@@ -1244,6 +1273,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.
@@ -1569,6 +1599,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:
@@ -1797,6 +1829,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
@@ -2489,11 +2524,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,
@@ -2501,6 +2531,15 @@ 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)) {
@@ -2530,6 +2569,13 @@ class LocalMiniappRuntime {
     }
   }
 
+  /** Put a promoted app's last main-view frame on the glasses; widget mode had refused it. */
+  private replayRetainedRender(packageName: string): void {
+    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;
@@ -3973,6 +4019,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") {
@@ -4008,6 +4062,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,
@@ -4629,7 +4690,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",
@@ -4709,7 +4770,7 @@ class LocalMiniappRuntime {
       let file: 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})
       } else {
@@ -5995,10 +6056,7 @@ class LocalMiniappRuntime {
   private static readonly ACTION_PAYLOAD_CAP = 256 * 1024
 
   /** Outstanding action invocations, keyed by host-generated callId. */
-  private actionCalls = new Map<
-    string,
-    {callerPackageName: string; targetPackageName: string; callerRequestId?: string; timer: number}
-  >()
+  private actionCalls = new PendingActionCalls(BgTimer, (value) => this.actionPayloadTooLarge(value))
   private actionCallSeq = 0
 
   private interopApps(): ClientApp[] {
@@ -6013,6 +6071,8 @@ class LocalMiniappRuntime {
   private async startInteropApp(packageName: string): Promise<boolean> {
     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
@@ -6074,7 +6134,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,
@@ -6268,6 +6329,8 @@ class LocalMiniappRuntime {
   private widgetCallSeq = 0
   /** Elements per widget frame; a card is small, and the link is slow. */
   private static readonly WIDGET_FRAME_ELEMENT_CAP = 64
+  /** Elements per expanded widget frame: the full screen, on the same link. */
+  private static readonly WIDGET_EXPANDED_FRAME_ELEMENT_CAP = 128
 
   private requireWidgetHost(packageName: string, requestId: string | undefined, op: string): boolean {
     return this.requirePermission(packageName, requestId, "HOST_WIDGETS", `to ${op} widgets`)
@@ -6316,6 +6379,7 @@ class LocalMiniappRuntime {
           name: widget.name,
           sizes: widget.sizes,
           defaultSize: widget.defaultSize,
+          expandable: widget.expandOnTap,
           running: app.running,
           compatible: app.compatibility?.isCompatible !== false,
         })
@@ -6327,7 +6391,8 @@ class LocalMiniappRuntime {
   private parseWidgetBox(raw: unknown): WidgetBox | null {
     const box = raw as {size?: unknown; width?: unknown; height?: unknown} | null
     if (!box || typeof box !== "object") return null
-    if (box.size !== "XS" && box.size !== "SM" && box.size !== "MD" && box.size !== "LG") return null
+    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)
     if (!(width > 0) || !(height > 0)) return null
@@ -6353,7 +6418,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.
    */
   private async handleWidgetPlace(
     hostPackageName: string,
@@ -6381,10 +6446,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)) miniappWidgetMode.setWidgetOnly(provider, true)
+    if (!app.running && !miniappRunningRegistry.has(provider)) miniappWidgetMode.setWidgetOnly(provider, true)
     try {
       await this.wakeInteropApp(provider)
     } catch (e) {
@@ -6400,7 +6467,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"),
+    })
   }
 
   private async handleWidgetUnplace(
@@ -6518,20 +6588,57 @@ class LocalMiniappRuntime {
     }
   }
 
-  /** 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. */
+  private handleWidgetExpandable(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
+    const widgetId = payload.widgetId as string | undefined
+    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. */
   private handleWidgetUpdate(providerPackageName: string, payload: Record<string, unknown>): void {
     const widgetId = payload.widgetId as string | undefined
     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)) return
-    if (elements.length > LocalMiniappRuntime.WIDGET_FRAME_ELEMENT_CAP || this.actionPayloadTooLarge(elements)) {
-      console.warn(`${LOG_TAG}: dropping oversized widget frame from ${providerPackageName}/${widgetId}`)
+    const widget = app ? this.declaredWidget(app, widgetId) : undefined
+    if (!widget) return
+    const view: WidgetView = 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} : {}),
+      })
     }
   }
 
@@ -6568,111 +6675,118 @@ class LocalMiniappRuntime {
     }
   }
 
+  /** 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. */
+  private static clampActionTimeout(raw: unknown): number {
+    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). */
+  private static readonly HOST_ACTION_CALLER = "host"
+
+  /** Installed, compatible, and declares the action — the same gates `invokeActionFromHost` applies up front. */
+  public hostActionAvailable(targetPackageName: string, actionId: string): boolean {
+    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.
    */
+  public async invokeActionFromHost(
+    targetPackageName: string,
+    actionId: string,
+    params: Record<string, unknown> = {},
+    timeoutMs?: number,
+  ): Promise<unknown> {
+    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. */
   private async handleActionInvoke(
     callerPackageName: string,
     payload: Record<string, unknown>,
     requestId?: string,
   ): Promise<void> {
-    const target = payload.targetPackageName as string | undefined
-    const actionId = payload.actionId as string | undefined
-    const params = (payload.params as Record<string, unknown> | undefined) ?? {}
-    // 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 as string | undefined,
+      payload.actionId as string | undefined,
+      (payload.params as Record<string, unknown> | undefined) ?? {},
+      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.
+   */
+  private async runActionInvoke(
+    callerPackageName: string,
+    callerIsSystem: boolean,
+    target: string | undefined,
+    actionId: string | undefined,
+    params: Record<string, unknown>,
+    timeoutMs: number,
+  ): Promise<ActionOutcome> {
+    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 as Error)?.message ?? `failed to wake ${target}`,
-      })
-      return
+      return fail(MiniappErrorCode.WAKE_FAILED, (e as Error)?.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",
@@ -6681,19 +6795,12 @@ 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,
@@ -6702,38 +6809,12 @@ 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. */
   private handleActionResult(targetPackageName: string, payload: Record<string, unknown>): void {
-    const callId = payload.callId as string | undefined
-    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 as ({code: string; message: string} & Record<string, unknown>) | undefined) ?? {
-        code: MiniappErrorCode.INTERNAL,
-        message: "action handler error",
-      }
-      this.sendResult(pending.callerPackageName, pending.callerRequestId, false, undefined, error)
-    }
+    this.actionCalls.handleResult(targetPackageName, payload)
   }
 
   private sendResult(