@glassly/engine 0.3.5-beta.734 → 0.3.5-beta.760

package/src/services/LocalLlmPrompt.ts

@@ -85,55 +85,74 @@ export function toTemplateTools(tools?: LlmTool[]): TemplateTool[] | undefined {
   }))
 }
 
-/** Rough tokens-per-character for a BPE vocabulary over mixed prose/JSON. */
-const CHARS_PER_TOKEN = 3.2
-/** Template framing per message (`<|im_start|>role … <|im_end|>`). */
-const TOKENS_PER_MESSAGE = 6
-
-export function estimateTokens(text: string): number {
-  return Math.ceil(text.length / CHARS_PER_TOKEN)
-}
-
-export function estimateMessageTokens(message: TemplateMessage): number {
-  let total = TOKENS_PER_MESSAGE + estimateTokens(message.content)
-  if (message.role === "assistant" && message.tool_calls) {
-    for (const call of message.tool_calls) total += estimateTokens(JSON.stringify(call.function)) + 8
-  }
-  return total
+export interface FittedLocalPrompt {
+  prompt: string
+  promptTokens: number
+  truncated: boolean
 }
 
-const MIN_TOOL_CONTENT_CHARS = 1_200
-
 /**
- * Fit the conversation into `budgetTokens`. History is grouped into turns
- * (a user message plus everything up to the next user message, so a tool
- * round stays with the question it answers); the oldest turns go first and
- * the last turn is never dropped — the model must at least see the question.
- * When that last turn alone still does not fit, tool outputs are cut to
- * their head.
+ * Measure the complete rendered prompt with the model's tokenizer, including
+ * template framing, system instructions and tool schemas. Drop old turns first,
+ * then shorten tool results / message text in the final turn. Never cut template
+ * delimiters, system instructions, or structured tool calls to make them fit.
  */
-export function fitToBudget(messages: TemplateMessage[], budgetTokens: number, toolTokens = 0): TemplateMessage[] {
-  const total = (list: TemplateMessage[]) => list.reduce((sum, m) => sum + estimateMessageTokens(m), toolTokens)
+export async function fitPromptToContext(
+  messages: TemplateMessage[],
+  budgetTokens: number,
+  render: (messages: TemplateMessage[]) => string,
+  countTokens: (prompt: string) => Promise<number>,
+): Promise<FittedLocalPrompt> {
+  if (!Number.isInteger(budgetTokens) || budgetTokens < 1) {
+    throw new Error("On-device model has no room for a prompt after reserving output tokens")
+  }
   const system = messages[0]?.role === "system" ? [messages[0]] : []
   const turns: TemplateMessage[][] = []
   for (const message of messages.slice(system.length)) {
     if (message.role === "user" || turns.length === 0) turns.push([message])
     else turns[turns.length - 1]!.push(message)
   }
-
-  while (turns.length > 1 && total([...system, ...turns.flat()]) > budgetTokens) {
-    turns.shift()
-  }
-
   let fitted = [...system, ...turns.flat()]
-  if (total(fitted) > budgetTokens) {
-    fitted = fitted.map((m) =>
-      m.role === "tool" && m.content.length > MIN_TOOL_CONTENT_CHARS
-        ? {...m, content: `${m.content.slice(0, MIN_TOOL_CONTENT_CHARS)}\n…[truncated]`}
-        : m,
-    )
+  let truncated = false
+  const marker = "\n…[truncated]…\n"
+  while (true) {
+    const prompt = render(fitted)
+    const promptTokens = await countTokens(prompt)
+    if (!Number.isInteger(promptTokens) || promptTokens < 1) {
+      throw new Error("On-device tokenizer returned an invalid prompt token count")
+    }
+    if (promptTokens <= budgetTokens) return {prompt, promptTokens, truncated}
+    truncated = true
+    if (turns.length > 1) {
+      turns.shift()
+      fitted = [...system, ...turns.flat()]
+      continue
+    }
+    // Preserve the user's question while tool output can still be shortened.
+    const candidates = fitted
+      .map((message, index) => ({message, index}))
+      .filter(({message}) => message.role !== "system" && Array.from(message.content).length > marker.length * 2)
+      .sort(
+        (a, b) =>
+          Number(b.message.role === "tool") - Number(a.message.role === "tool") ||
+          b.message.content.length - a.message.content.length,
+      )
+    const candidate = candidates[0]
+    if (!candidate) {
+      throw new Error(
+        `On-device prompt instructions and tool definitions exceed the context budget (${promptTokens} > ${budgetTokens} tokens)`,
+      )
+    }
+    // Keep both ends of long transcripts and questions, without splitting a
+    // Unicode code point. Each pass shrinks strictly, then remeasures the whole
+    // rendered prompt; character ratios are never used as a safety check.
+    const chars = Array.from(candidate.message.content)
+    const keep = Math.floor(chars.length / 4)
+    fitted[candidate.index] = {
+      ...candidate.message,
+      content: `${chars.slice(0, keep).join("")}${marker}${chars.slice(-keep).join("")}`,
+    }
   }
-  return fitted
 }
 
 /** Remove a leading `<think>…</think>` block (or an unterminated one). */

package/src/services/LocalLlmProvider.ts

@@ -22,9 +22,8 @@ import {BgTimer} from "../utils/timers"
 import localLlmModelManager, {type LocalLlmModelId} from "./LocalLlmModelManager"
 import {
   buildTemplateMessages,
-  estimateTokens,
   finalizeLocalResult,
-  fitToBudget,
+  fitPromptToContext,
   toTemplateTools,
   type LocalCompletion,
 } from "./LocalLlmPrompt"
@@ -33,6 +32,7 @@ import {SETTINGS, useSettingsStore} from "../stores/settings"
 type Rne = typeof import("react-native-executorch")
 // The runner API lives on the `llm` namespace; derive its types from there so
 // the import stays a type-only reference (no native module at load time).
+type Tokenizer = ReturnType<Rne["nlp"]["loadTokenizer"]>
 type LLMRunner = ReturnType<Rne["llm"]["createLLMRunner"]>
 type LLMGenerationStats = ReturnType<LLMRunner["generate"]>
 type LLMGenerationConfig = NonNullable<Parameters<LLMRunner["generate"]>[1]>
@@ -45,12 +45,14 @@ const IDLE_UNLOAD_MS = 5 * 60_000
 const GENERATION_DEADLINE_MS = 100_000
 const DEFAULT_MAX_NEW_TOKENS = 512
 const MAX_NEW_TOKENS_CEILING = 1_024
-/** Headroom between the estimated prompt and the context end; estimates are rough. */
+/** Reserve space for runner-added BOS/EOS tokens and context boundary bookkeeping. */
 const CONTEXT_MARGIN_TOKENS = 96
 
 interface LoadedModel {
   modelId: LocalLlmModelId
   runner: LLMRunner
+  tokenizer: Tokenizer
+  countTokens: (tokenizer: Tokenizer, prompt: string) => Promise<number>
   template: Template
   stopTokens: string[]
   maxSeqLen: number
@@ -85,6 +87,11 @@ function generateWorklet(
   return {text, stats}
 }
 
+function countTokensWorklet(tokenizer: Tokenizer, prompt: string): number {
+  "worklet"
+  return tokenizer.encode(prompt).length
+}
+
 class LocalLlmProvider {
   private static instance: LocalLlmProvider
 
@@ -150,6 +157,8 @@ class LocalLlmProvider {
       loaded.runner.dispose()
     } catch (error) {
       console.warn(`${LOG_TAG}: runner dispose failed:`, error)
+    } finally {
+      loaded.tokenizer.dispose()
     }
   }
 
@@ -159,21 +168,21 @@ class LocalLlmProvider {
       const model = await this.ensureLoaded()
       const jsonMode = request.jsonMode === true
       const tools = toTemplateTools(request.tools)
-      const toolTokens = tools ? estimateTokens(JSON.stringify(tools)) + 64 : 0
 
       const maxNewTokens = Math.max(
         16,
         Math.min(request.maxTokens ?? DEFAULT_MAX_NEW_TOKENS, MAX_NEW_TOKENS_CEILING, Math.floor(model.maxSeqLen / 4)),
       )
       const promptBudget = model.maxSeqLen - maxNewTokens - CONTEXT_MARGIN_TOKENS
-      const messages = fitToBudget(buildTemplateMessages({...request, jsonMode}), promptBudget, toolTokens)
-
-      const prompt = model.template.render({
-        messages,
-        tools,
-        add_generation_prompt: true,
-        enable_thinking: false,
-      })
+      const {prompt, promptTokens, truncated} = await fitPromptToContext(
+        buildTemplateMessages({...request, jsonMode}),
+        promptBudget,
+        (messages) => model.template.render({messages, tools, add_generation_prompt: true, enable_thinking: false}),
+        (text) => model.countTokens(model.tokenizer, text),
+      )
+      console.log(
+        `${LOG_TAG}: ${model.modelId} prompt=${promptTokens} budget=${promptBudget} context=${model.maxSeqLen} maxNewTokens=${maxNewTokens} truncated=${truncated}`,
+      )
 
       model.runner.reset(0)
       const deadline = BgTimer.setTimeout(() => {
@@ -189,6 +198,12 @@ class LocalLlmProvider {
           {maxNewTokens, temperature: request.temperature ?? 0.7},
           model.stopTokens,
         )
+      } catch (error) {
+        console.warn(
+          `${LOG_TAG}: generation failed: model=${model.modelId} prompt=${promptTokens} context=${model.maxSeqLen} maxNewTokens=${maxNewTokens}`,
+          error,
+        )
+        throw error
       } finally {
         BgTimer.clearTimeout(deadline)
       }
@@ -246,16 +261,28 @@ class LocalLlmProvider {
     const startedAt = Date.now()
     const createRunner = rne.wrapAsync(rne.llm.createLLMRunner)
     const runner = await createRunner(paths.model, paths.tokenizer, [])
-    const maxSeqLen = runner.getKVCacheState().maxSeqLen
-    console.log(`${LOG_TAG}: loaded ${modelId} (context ${maxSeqLen}) in ${Date.now() - startedAt} ms`)
-
-    return {
-      modelId,
-      runner,
-      template,
-      stopTokens: [...tokenizerConfig.stopTokens],
-      maxSeqLen,
-      generate: rne.wrapAsync(generateWorklet),
+    let tokenizer: Tokenizer | undefined
+    try {
+      const maxSeqLen = runner.getKVCacheState().maxSeqLen
+      if (!Number.isInteger(maxSeqLen) || maxSeqLen <= CONTEXT_MARGIN_TOKENS + 16) {
+        throw new Error(`On-device model ${modelId} reported an invalid context size: ${maxSeqLen}`)
+      }
+      tokenizer = await rne.wrapAsync(rne.nlp.loadTokenizer)(paths.tokenizer)
+      console.log(`${LOG_TAG}: loaded ${modelId} (context ${maxSeqLen}) in ${Date.now() - startedAt} ms`)
+      return {
+        modelId,
+        runner,
+        tokenizer,
+        countTokens: rne.wrapAsync(countTokensWorklet),
+        template,
+        stopTokens: [...tokenizerConfig.stopTokens],
+        maxSeqLen,
+        generate: rne.wrapAsync(generateWorklet),
+      }
+    } catch (error) {
+      tokenizer?.dispose()
+      runner.dispose()
+      throw error
     }
   }
 

package/src/services/LocalMiniappRuntime.ts

@@ -162,6 +162,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"
@@ -6021,10 +6028,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[] {
@@ -6596,111 +6600,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",
@@ -6709,19 +6720,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,
@@ -6730,38 +6734,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(

package/src/services/SceneRenderer.ts

@@ -66,7 +66,9 @@ const MAX_SETTLE_MS = 255 * 33
 function settleTimeOf(elements: FrameElement[]): number {
   let ms = 0
   for (const el of elements) {
-    if (el.change !== "updated" && el.change !== "moved") continue
+    // Entering and leaving elements tween too, from or to their offset.
+    const edge = el.transition?.exit !== undefined || (el.change === "created" && el.transition?.enter !== undefined)
+    if (el.change !== "updated" && el.change !== "moved" && !edge) continue
     const t = el.transition?.durationMs ?? 0
     // Rotation has its own millisecond clock, beyond the geometry frame limit.
     const duration = Math.min(t, el.rotation !== undefined ? 65535 : MAX_SETTLE_MS)

package/src/services/actionInvoke.ts

@@ -0,0 +1,105 @@
+import {MiniappErrorCode} from "@glassly/miniapp"
+
+import type {ClientApp} from "../types/applet"
+
+export type ActionError = {code: string; message: string} & Record<string, unknown>
+export type ActionOutcome = {ok: true; data: unknown} | {ok: false; error: ActionError}
+
+export const actionFailure = (code: string, message: string): ActionOutcome => ({ok: false, error: {code, message}})
+
+/** Installed, compatible, and declares the action. */
+export function appDeclaresAction(app: ClientApp | undefined, actionId: string): boolean {
+  if (!app) return false
+  if (app.compatibility && app.compatibility.isCompatible === false) return false
+  return (app.actions ?? []).some((a) => a.id === actionId)
+}
+
+/**
+ * Gates shared by miniapp->miniapp invoke and host invoke. Declared actions are
+ * public by default; `visibility: "system"` ones need a system caller.
+ */
+export function checkActionAccess(
+  app: ClientApp | undefined,
+  target: string | undefined,
+  actionId: string | undefined,
+  callerIsSystem: boolean,
+): ActionError | null {
+  if (!target || !app) {
+    return {
+      code: MiniappErrorCode.APP_NOT_FOUND,
+      message: `Miniapp not found: ${target ?? "(missing targetPackageName)"}`,
+    }
+  }
+  if (!actionId) return {code: MiniappErrorCode.ACTION_NOT_FOUND, message: "invoke requires an actionId"}
+  if (app.compatibility && app.compatibility.isCompatible === false) {
+    return {
+      code: MiniappErrorCode.APP_NOT_COMPATIBLE,
+      message: `${target} is not compatible with the connected glasses`,
+    }
+  }
+  const declared = (app.actions ?? []).find((a) => a.id === actionId)
+  if (!declared) {
+    return {code: MiniappErrorCode.ACTION_NOT_FOUND, message: `${target} does not declare action "${actionId}"`}
+  }
+  if (declared.visibility === "system" && !callerIsSystem) {
+    return {
+      code: MiniappErrorCode.NOT_PERMITTED,
+      message: `Action "${actionId}" on ${target} is restricted to system apps`,
+    }
+  }
+  return null
+}
+
+/** BgTimer's shape; passed in so this module stays loadable without the native timer. */
+export interface ActionTimers {
+  setTimeout: (cb: () => void, ms: number) => number
+  clearTimeout: (id: number) => void
+}
+
+/** Outstanding ACTION_CALLs awaiting an ACTION_RESULT, keyed by host-generated callId. */
+export class PendingActionCalls {
+  private readonly calls = new Map<string, {target: string; settle: (o: ActionOutcome) => void; timer: number}>()
+
+  constructor(
+    private readonly timers: ActionTimers,
+    private readonly payloadTooLarge: (value: unknown) => boolean,
+  ) {}
+
+  /** Register a call; resolves with its outcome, or ACTION_TIMEOUT. */
+  register(callId: string, target: string, actionId: string, timeoutMs: number): Promise<ActionOutcome> {
+    return new Promise((resolve) => {
+      const timer = this.timers.setTimeout(() => {
+        this.calls.delete(callId)
+        resolve(actionFailure(MiniappErrorCode.ACTION_TIMEOUT, `action "${actionId}" timed out after ${timeoutMs}ms`))
+      }, timeoutMs)
+      this.calls.set(callId, {target, settle: resolve, timer})
+    })
+  }
+
+  /** Settle from a target's ACTION_RESULT payload. Only the invoked target may resolve a call. */
+  handleResult(targetPackageName: string, payload: Record<string, unknown>): void {
+    const callId = payload.callId as string | undefined
+    if (!callId) return
+    const pending = this.calls.get(callId)
+    // callIds are guessable (timestamp + seq): a different miniapp must not spoof someone else's result.
+    if (!pending || pending.target !== targetPackageName) return
+    this.calls.delete(callId)
+    this.timers.clearTimeout(pending.timer)
+
+    if (payload.ok === true) {
+      if (this.payloadTooLarge(payload.result)) {
+        pending.settle(actionFailure(MiniappErrorCode.PAYLOAD_TOO_LARGE, "action result exceeded the 256 KB cap"))
+        return
+      }
+      pending.settle({ok: true, data: payload.result ?? null})
+      return
+    }
+    pending.settle({
+      ok: false,
+      error: (payload.error as ActionError | undefined) ?? {
+        code: MiniappErrorCode.INTERNAL,
+        message: "action handler error",
+      },
+    })
+  }
+}