@glassly/engine 0.1.0-dev.0

package/build/services/LocalMiniappRuntime.d.ts

@@ -0,0 +1,677 @@
+/**
+ * LocalMiniappRuntime
+ *
+ * Singleton service that bridges local miniapps (running in WebViews) with
+ * phone capabilities: display, audio, storage, sensors, LED, etc.
+ *
+ * Each miniapp communicates via the @glassly/miniapp envelope protocol.
+ * This runtime handles request dispatch, stream fan-out, and lifecycle
+ * management (connect/disconnect/ping).
+ */
+import { type MiniappRuntimeDiagnosticSnapshot } from "../utils/miniappDiagnostics";
+export interface InstalledMiniappManifest {
+    packageName?: string;
+    /** Human-facing app name (from miniapp.json `name`). Shown in the "Starting
+     * <name>…" boot message; falls back to the package name when absent. */
+    name?: string;
+    version?: string;
+    sdkVersion?: string;
+    minHostVersion?: string;
+    type?: string;
+    entry?: {
+        background?: string;
+        ui?: string;
+    };
+    permissions?: Array<{
+        type: string;
+        required?: boolean;
+        description?: string;
+    }>;
+    hardwareRequirements?: Array<{
+        type: string;
+        level: string;
+        description?: string;
+    }>;
+    actions?: Array<{
+        id?: unknown;
+        description?: unknown;
+        parameters?: unknown;
+        outputSchema?: unknown;
+    }>;
+}
+type TranscriptionEventSource = "cloud" | "local";
+declare class LocalMiniappRuntime {
+    private static instance;
+    /**
+     * Host hook: a platform-funded feature was refused because the account's
+     * free-tier allowance is spent — "llm" for a refused ai.complete, and
+     * "transcription" when the cloud pushes an STT quota block. The app wires
+     * this to an upgrade prompt (see jsBootstrap); fires per refusal, so the
+     * host side owns any once-per-session throttling. For "transcription",
+     * `info.localSttActive` says whether on-device sherpa took over (model was
+     * downloaded) so the prompt can say captions continue vs stopped.
+     */
+    onQuotaExceeded: ((feature: "llm" | "transcription", info?: {
+        localSttActive: boolean;
+    }) => void) | null;
+    /**
+     * Host hook: a previously-refused feature is available again — the cloud
+     * pushed an STT unblock, or a metered LLM call succeeded after a quota
+     * refusal (new month, upgrade). Lets the app re-arm its upgrade prompt so
+     * the NEXT refusal prompts again instead of staying silenced all session.
+     */
+    onQuotaRestored: ((feature: "llm" | "transcription") => void) | null;
+    /** Last time the quota notice was drawn on the glasses; debounces re-shows. */
+    private lastSttQuotaNoticeAt;
+    /** True after a metered (platform-funded) LLM call was refused for quota. */
+    private llmQuotaBlocked;
+    /** Connected miniapps keyed by packageName. */
+    private connectedApps;
+    /**
+     * Packages that have completed their CONNECT handshake (sent
+     * `miniapp_connect`, got `CONNECT_ACK`). Distinct from `connectedApps`,
+     * which is populated at spawn/registration time — handshake is later.
+     * Drives {@link waitForConnect}.
+     */
+    private handshookApps;
+    /** Pending {@link waitForConnect} resolvers, keyed by packageName. */
+    private connectWaiters;
+    /** Ref-counted stream subscriptions: stream → set of packageNames. */
+    private streamSubscribers;
+    /** Host observers for the Mentra Live button-capture policy. */
+    private buttonPressSubscriberListeners;
+    /** Guards one-time wiring of the cloud transcript/translation fan-out. */
+    private cloudResultsWired;
+    private cloudStatusWired;
+    private capabilitiesWired;
+    private cloudAudioSubscriptionSync;
+    /**
+     * Per-miniapp language hints from TRANSCRIPTION_CONFIG (issue 021 WP3).
+     * Bare ISO 639-1 codes, already registry-validated by the SDK and
+     * re-normalized here (defense in depth). Merged (union) into the auto-mode
+     * cloud transcription subscription in buildCloudAudioSubscriptions.
+     */
+    private transcriptionHintsByApp;
+    /** Ping interval handle. */
+    private pingIntervalId;
+    private foregroundProbeTimers;
+    /**
+     * Notified when a miniapp is unregistered for missing liveness pings.
+     * JSRouter wires this into its crash-respawn machinery so a
+     * silently-stalled background script is restarted (with crash-loop
+     * protection) instead of staying dead — a dead background drops its
+     * subscriptions, which releases the mic while the webview still looks
+     * alive.
+     */
+    onLivenessTimeout: ((packageName: string) => void) | null;
+    /** Pending cloud requests: requestId → packageName that originated the request. */
+    private pendingCloudRequests;
+    private speechRuns;
+    private localSecret;
+    private usedTokens;
+    private constructor();
+    /** Snapshot of miniapps actively subscribed to hardware button events. */
+    getButtonPressSubscribers(): string[];
+    /** Observe active hardware-button subscriptions. */
+    onButtonPressSubscribersChanged(listener: (packageNames: string[]) => void): () => void;
+    /** Report-safe live miniapp/subscription/resource snapshot. */
+    getDiagnosticSnapshot(nowMs?: number): MiniappRuntimeDiagnosticSnapshot;
+    private replaceStreamSubscribers;
+    /** Mirror the live transcription/translation subscriber sets into the debug store. */
+    private publishTranscriptionDebugSubscribers;
+    /**
+     * Generate an HMAC-signed local session token for browser fallback auth.
+     * Token format: base64(JSON({userId, packageName, exp})).base64(HMAC-SHA256(payload, secret))
+     * Single-use, 5-minute TTL.
+     */
+    generateLocalToken(userId: string, packageName: string): string;
+    /**
+     * Validate and consume a local session token. Single-use.
+     */
+    validateLocalToken(token: string): {
+        userId: string;
+        packageName: string;
+    } | null;
+    /**
+     * Simple HMAC-SHA256 using Web Crypto API (available in React Native).
+     * Returns base64url-encoded signature.
+     * Falls back to a simpler hash if crypto.subtle is not available.
+     */
+    private hmacSign;
+    static getInstance(): LocalMiniappRuntime;
+    private initialized;
+    /**
+     * Initialize the runtime. Called from MantleManager.init().
+     * Idempotent — safe to call multiple times.
+     */
+    initialize(): void;
+    /**
+     * Handle an incoming cloud message relayed from the v2 cloud session
+     * (phone_stream_status, phone_managed_stream_status).
+     *
+     * Routes the response back to the originating miniapp via the requestId
+     * that was stored when the miniapp first made the request.
+     */
+    handleCloudMessage(msg: any): void;
+    /**
+     * Register a pending cloud request so we can route the response back.
+     */
+    registerPendingCloudRequest(requestId: string, packageName: string, envelopeRequestId?: string): void;
+    registerApp(packageName: string, sendFn: (raw: string) => void, installedManifest?: InstalledMiniappManifest): void;
+    /**
+     * Resolve once `packageName` has completed its CONNECT handshake. If it has
+     * already connected, resolves immediately. Rejects if the timeout elapses
+     * first, or if the app is unregistered while waiting.
+     *
+     * Used by the launcher's `ensureConnected` (and thus the action broker) so a
+     * just-spawned target is known to be live before anything is delivered to it.
+     */
+    waitForConnect(packageName: string, timeoutMs: number): Promise<void>;
+    /** Resolve/reject all pending {@link waitForConnect} waiters for a package. */
+    private flushConnectWaiters;
+    /**
+     * Invalidate the CONNECT handshake for a package whose native context is
+     * being replaced WITHOUT going through register/unregister — i.e. a crash
+     * respawn. Without this, {@link waitForConnect} would treat the dead/
+     * not-yet-initialized context as connected and deliver to it. Pending waiters
+     * are failed so a wake mid-respawn retries rather than hanging.
+     */
+    resetHandshake(packageName: string): void;
+    /**
+     * Attach (or update) the installedManifest for an already-registered app.
+     * Used when the manifest is fetched asynchronously (dev miniapps) after the
+     * miniapp has already CONNECTed — preserves existing subscriptions.
+     */
+    setInstalledManifest(packageName: string, installedManifest: InstalledMiniappManifest): void;
+    /**
+     * Graceful version of {@link unregisterApp}: notify the miniapp via
+     * `WILL_DISCONNECT`, wait ~50ms so its `beforeDisconnect` handlers can
+     * fire one last `sendOneShot` (e.g. `display.clear()`), then run the
+     * normal teardown. Use this for any disconnect path where the socket
+     * is still open. For ungraceful paths (transport already closed),
+     * call {@link unregisterApp} directly — the heads-up would be
+     * undeliverable anyway.
+     */
+    gracefullyUnregisterApp(packageName: string, reason?: string): Promise<void>;
+    unregisterApp(packageName: string, opts?: {
+        endNavigation?: boolean;
+    }): void;
+    handleRawMessage(packageName: string, raw: string): void;
+    private handleConnect;
+    private requestMiniappAuth;
+    private handleAuthRefresh;
+    private refreshMiniappAuth;
+    private authRefreshOptions;
+    private scheduleMiniappAuthRefresh;
+    private clearMiniappAuthRefresh;
+    /**
+     * Deliver the miniapp's FIRST auth token, retrying until it lands. Called from
+     * {@link handleConnect} when the initial mint didn't resolve in the CONNECT_ACK
+     * window. `inFlight` lets attempt 0 reuse the mint the handshake already
+     * started (avoids a redundant duplicate request); later attempts mint fresh.
+     *
+     * A `null` result means auth is fundamentally unavailable (no miniappAuth hook)
+     * — permanent, so we do NOT retry. A REJECTION means a transient failure
+     * (typically the cloud client isn't connection-ready yet) — retry with backoff.
+     * Either way we bail if the app has since disconnected or already got a token
+     * (e.g. via {@link redriveMiniappAuthDelivery} on cloud-connect).
+     */
+    private deliverInitialMiniappAuth;
+    private scheduleInitialMiniappAuthRetry;
+    private clearMiniappAuthDeliveryRetry;
+    /**
+     * When the cloud client (re)connects, immediately re-attempt the initial mint
+     * for any handshook app still missing its token, instead of waiting out the
+     * backoff. This is what turns "scan a dev app before the cloud is ready" from
+     * "dead until you manually reconnect Cloud V2" into "authenticates on its own
+     * the instant the connection comes up".
+     */
+    private redriveMiniappAuthDelivery;
+    /**
+     * TRANSCRIPTION_CONFIG (issue 021 WP3): store the miniapp's language hints
+     * and rebuild the cloud subscription set so the auto-mode subscription
+     * carries them. Replies with a REQUEST_RESULT so the SDK's configure()
+     * promise settles: unknown hint values are an error, not a silent drop.
+     */
+    private handleTranscriptionConfig;
+    private handleSubscribe;
+    private handleCalendarListEvents;
+    /**
+     * For state-bearing streams (battery, connection), deliver the current value
+     * immediately on subscribe. Other streams (button press, transcription, etc.)
+     * are pure event streams with no "current value" to snapshot.
+     */
+    private emitInitialSnapshots;
+    /**
+     * Read the phone's battery state right now and emit it as the given stream.
+     * Used for both phone_battery snapshot on subscribe, and as a stand-in for
+     * glasses_battery when connected to Simulated Glasses.
+     */
+    private emitPhoneBatteryAs;
+    private handleDisplay;
+    /**
+     * Scene render (session.display.render()). Same arbitration as DISPLAY, but
+     * the payload is a whole frame of positioned elements and the caller may be
+     * awaiting the outcome: LocalDisplayManager guarantees the resolver fires
+     * exactly once (displayed/blocked, with degraded/dropped reporting), and that
+     * becomes the REQUEST_RESULT data.
+     */
+    private handleRender;
+    /**
+     * Native nav UI feed (display.sendNativeNav*). Gated on the device's nav
+     * mode being active (trip-scoped); the miniapp's first pushes can race the
+     * host-side trip start, so "unsupported" here is transient and the miniapp
+     * just retries on its next tick.
+     */
+    private handleNativeNav;
+    /** Bring the glasses' native dashboard (OS idle screen) to the foreground. */
+    private handleShowNativeDashboard;
+    private handlePlayAudio;
+    private handleStopAudio;
+    /** Valid PCM sample rates for speaker streams. Mirrors the SDK contract. */
+    private static readonly SPEAKER_STREAM_SAMPLE_RATES;
+    private static readonly SPEAKER_STREAM_MAX_BASE64_CHARS;
+    private speakerStreamCounter;
+    private handleSpeakerStreamOpen;
+    /** Resolve + validate a stream id from a payload against the app's active stream. */
+    private activeSpeakerStream;
+    private handleSpeakerStreamWrite;
+    private handleSpeakerStreamClose;
+    private handleSpeakerStreamAbort;
+    private handleSpeak;
+    private cancelSpeech;
+    private handleRgbLed;
+    private handleLocationPoll;
+    /**
+     * All navigation handlers + their state live in NavigationHandlers. The
+     * dispatcher's NAVIGATION_* cases delegate here; the rest of the runtime
+     * cross-cuts navigation through {@link NavigationHandlers.onDisconnect}
+     * (mini-app disconnect) and {@link NavigationHandlers.isTripActive}
+     * (location-stream gating during a trip).
+     */
+    private readonly navigationHandlers;
+    /**
+     * `session.blob` — persistent, per-app binary storage. Like NavigationHandlers,
+     * the BLOB_* dispatcher cases delegate here. It's a generic byte store; audio
+     * recording lives entirely in the miniapp (mic.onAudioChunk → chunked
+     * BLOB_WRITE), so nothing audio-specific runs in the host.
+     */
+    private readonly blobStore;
+    private readonly blobRequestQueues;
+    private readonly simpleStorage;
+    /**
+     * BlobStore's file helpers are synchronous once a user namespace is selected,
+     * but first-boot Core auth is not. Queue requests per app behind stable
+     * identity resolution so CREATE/WRITE/COMMIT ordering survives that wait.
+     */
+    private enqueueBlobRequest;
+    private handleBlobRequestError;
+    /**
+     * Heading is a sensor stream — start the native compass when any mini
+     * app is subscribed to "heading_update", stop it when none are.
+     */
+    private headingUnsub;
+    private recomputeHeadingSubscription;
+    /**
+     * Accelerometer is a sensor stream — enable the glasses IMU when any mini
+     * app is subscribed to "accel_data", disable it when none are. Mirrors the
+     * heading pattern. Only G2 streams IMU today; on other devices the native
+     * call is a no-op so this is harmless.
+     */
+    private imuEnabled;
+    private recomputeImuSubscription;
+    /**
+     * Last rate we asked the host for. Lets us skip the cross-process call
+     * when nothing actually changed (most SUBSCRIBE / unregister churn
+     * leaves the aggregate unchanged) and tracks state for the no-active-
+     * subscribers → tell host to back off case.
+     */
+    private lastAppliedLocationRate;
+    /**
+     * Recompute the aggregate location tier across every connected
+     * miniapp and push the result to the host. The aggregate is the
+     * STRICTEST rate any single app has requested — see
+     * {@link LOCATION_RATE_PRIORITY} — because the GPS sample rate is a
+     * shared OS-level setting that we can't bias per-app.
+     *
+     * Called after every SUBSCRIBE and every unregister so that when a
+     * realtime-requesting app goes away the tier falls back down. If no
+     * connected app is asking for a location rate, we tell the host
+     * "off" so it can drop GPS power.
+     */
+    private recomputeLocationTier;
+    private handleStorageGet;
+    private handleStorageSet;
+    private handleStorageDelete;
+    private handleStorageList;
+    private handleStorageClear;
+    private handleStorageHas;
+    private handleStorageGetAll;
+    private handleStorageSetMultiple;
+    private handleSetWifiAdbState;
+    /**
+     * Resolve an enrolled-speaker id (`spk_…`) to its display name. Gated on the
+     * SPEAKERS manifest permission: names are on-device PII — transcription
+     * events deliberately carry only opaque ids, and this explicit, user-visible
+     * declaration is the one gate that lets a miniapp turn an id into a name.
+     * Non-enrolled ids (anonymous diarization labels, deleted profiles) resolve
+     * to null.
+     */
+    private handleSpeakersResolveName;
+    /**
+     * Serve every MEMORY_* request against the engine's user-scoped MemoryStore.
+     * Gated on the MEMORY manifest permission: the store is shared across
+     * miniapps (it is the user's timeline, not the app's), so access is an
+     * explicit declaration the user can see, like MICROPHONE.
+     */
+    private handleMemoryRequest;
+    /**
+     * Serve session.keys.get(provider): read a user-supplied provider API key
+     * from the device-local settings store and hand it to the miniapp. Gated on
+     * the API_KEYS manifest permission and the MINIAPP_READABLE_API_KEYS
+     * allowlist. The key crosses only the local bridge — it is never sent to
+     * any server by this path. "mapbox" alone resolves further: with no user
+     * key saved it serves the public render token fetched from Glassly Cloud
+     * (the binary bakes none), and null when that's unavailable too — e.g.
+     * cloud disabled (see the allowlist note).
+     */
+    private handleKeysGet;
+    /**
+     * Serve session.ai.complete(). Gated on the AI manifest permission.
+     *
+     * The request names a TIER; this handler resolves it to a provider+model
+     * (Settings > AI Models dropdowns, or auto from saved keys) and then picks
+     * one of two transport paths, decided by whether the user saved a key for
+     * the resolved provider (Settings > API Keys) — the phone is where both
+     * settings live, so this is the only place the choice can be made:
+     *
+     *  - User key saved → the phone calls the vendor DIRECTLY via
+     *    @glassly/llm-providers (the same implementations the cloud runtime
+     *    uses). The request never transits Glassly Cloud, works with the cloud
+     *    disabled, bills the user's own account, and is not metered — matching
+     *    the Soniox and Mapbox user-key patterns.
+     *  - No user key → relay to the cloud LLM service (platform key, metered).
+     *
+     * Either way the miniapp never sees a provider credential — the key is read
+     * host-side only, unlike session.keys.get() which deliberately exposes it.
+     */
+    private handleAiComplete;
+    /**
+     * ai.generate — agentic visual generation. Always relayed to the cloud
+     * runtime (the server drives the provider's agentic loop; there is no
+     * phone-direct path — the beta tool surface only exists server-side). A
+     * saved Anthropic user key still rides along as the billing key so BYO
+     * users aren't metered, matching handleAiComplete's intent.
+     */
+    private handleAiGenerate;
+    /**
+     * Drive one generate run through the cloud's pollable job surface, so the
+     * miniapp gets live activity ticks (via the internal `_ai_generate_progress`
+     * stream, correlated by the caller's `progressToken`) and an abandoned run
+     * is cancelled instead of billing to completion. Clouds that predate the
+     * surface answer 404 on job start — fall back to the sync route (one long
+     * POST, no ticks), which stays deployed for exactly this skew window.
+     */
+    private runGenerateJob;
+    private handleCameraFov;
+    /**
+     * Explicit IMU enable/disable from a miniapp (session.imu.setEnabled).
+     *
+     * The accel stream already auto-toggles the native IMU on subscribe (see
+     * {@link recomputeImuSubscription}); this is a direct override. We sync
+     * `this.imuEnabled` to the requested state so a subsequent subscription
+     * recompute with the same aggregate doesn't issue a redundant native call.
+     * Note that a later subscribe/unsubscribe that changes the aggregate will
+     * still re-derive the sensor state from subscriptions.
+     */
+    private handleImuSetEnabled;
+    /**
+     * Lifecycle-scoped glasses-side VAD override from a miniapp
+     * (session.mic.setVoiceActivityDetectionEnabled). Requires MICROPHONE in the
+     * miniapp manifest. Mentra Live only today — other models no-op via DeviceStore.
+     */
+    private handleMicSetVadEnabled;
+    /**
+     * Lifecycle-scoped center-mic loudness gate ("Barrier") override from a miniapp
+     * (session.mic.setLoudnessGateEnabled). Requires MICROPHONE in the miniapp
+     * manifest. Mentra Live only today — other models no-op via DeviceStore.
+     */
+    private handleMicSetLoudnessGateEnabled;
+    /**
+     * session.system.scanQr — host camera overlay. Must not clear miniapp
+     * foreground; the host seam is responsible for presenting a Modal on top.
+     */
+    private handleScanQr;
+    private handleShare;
+    private handleOpenUrl;
+    private handleCopyClipboard;
+    private handleDownload;
+    private handlePhoto;
+    private handleCameraWarmUp;
+    private handleVideoRecordingStart;
+    private handleVideoRecordingStop;
+    /**
+     * Stream handlers — dispatched to the engine PhoneStreamCoordinator. For managed
+     * streams the coordinator additionally calls the v2 client REST route to
+     * provision Cloudflare. Cloud-SDK apps (third-party developers) use a
+     * separate cloud-side path that does not pass through here.
+     */
+    private handleStreamStart;
+    private handleStreamStop;
+    private handleManagedStreamStart;
+    private handleManagedStreamStop;
+    /**
+     * session.glasses.requestWifiSetup — open the phone's glasses Wi-Fi setup
+     * flow. The host owns the actual UI via the `engine.configure({ui})` seam;
+     * this just forwards the request and reports success/failure.
+     */
+    private handleRequestWifiSetup;
+    /**
+     * Wire the PhoneStreamCoordinator's status callback so coordinator-emitted
+     * updates become `EVENT { streamType: "stream_status" }` envelopes on the
+     * subscribing miniapp(s).
+     */
+    wireStreamingStatusFanout(): void;
+    /**
+     * Standalone subscribe — lets external code subscribe a registered miniapp to
+     * streams without going through the envelope protocol.
+     *
+     * Returns `{ok: true}` on success, or `{ok: false, error}` on failure.
+     */
+    subscribe(packageName: string, streams: string[]): {
+        ok: boolean;
+        error?: string;
+    };
+    private getConfiguredMicGates;
+    private recomputeMicRequirements;
+    /**
+     * Recompute the aggregated v2 cloud subscription list across all local miniapps.
+     *
+     * Cloud-dependent streams (transcription:*, translation:*) only flow if the
+     * v2 runtime knows the phone wants them. Local-only streams (button_press, etc.)
+     * are NOT sent — they come from the Bluetooth SDK, not from cloud.
+     */
+    private updateCloudSubscriptions;
+    /**
+     * Build the cloud `AudioSubscription[]` from the miniapp cloud-stream key set.
+     *
+     * Stream keys: `transcription:<lang>` (lang may be `auto`, `en-US`, …) and
+     * `translation:<source>:<target>` (3 colon-parts; source/target may be `*`
+     * or `auto` wildcards, target may also be `*`). The cloud protocol requires a
+     * concrete `target: string` for translation, so wildcard-target translation
+     * keys (`translation:<source>:*`, `translation:*:*`, `translation:auto`) have
+     * no cloud equivalent and are skipped. Wildcard/`auto` SOURCE maps to
+     * `{mode: "auto"}`.
+     */
+    private buildCloudAudioSubscriptions;
+    private audioSubscriptionKey;
+    /**
+     * Wire the cloud's transcription/translation results into the existing
+     * miniapp fan-out exactly once. Maps each cloud result back to the
+     * cloud-to-app data shape `forwardEvent` already forwards, keyed on the
+     * `transcription:<lang>` / `translation:<source>:<target>` stream strings, so
+     * subscribed miniapps receive identical envelopes.
+     */
+    private ensureCloudResultsWired;
+    /**
+     * A platform-billed LLM call succeeded. If quota had been refused earlier,
+     * the allowance is back (new month, upgrade) — tell the host so its
+     * upgrade prompt re-arms for the next refusal.
+     */
+    private noteMeteredLlmSuccess;
+    private handleTranscriptionData;
+    private handleTranslationData;
+    /** Re-partition audio routing after a Soniox-direct enable/disable flip. */
+    recomputeAudioRouting(): void;
+    /**
+     * Whether the primary transcription provider is up: Soniox-direct session
+     * health when a user API key is set, cloud connectivity otherwise. Drives
+     * the local/default delivery routing in forwardEvent — under Soniox-direct
+     * the cloud can be connected while transcription is down (and vice versa).
+     * A plan-quota block counts as down: the cloud stays connected but closes
+     * its STT streams, and local sherpa transcripts must reach default-route
+     * subscribers.
+     */
+    private transcriptionPrimaryUp;
+    private ensureCloudStatusWired;
+    /** Model profile + runtime overrides (the G2 CFW scene canvas) for the default wearable. */
+    private currentCapabilities;
+    /**
+     * The scene canvas can change after a miniapp's CONNECT_ACK (CFW is
+     * detected from the glasses' settings response, which may land after the
+     * handshake) — push the new capabilities so render() boxes use the real
+     * canvas.
+     */
+    private ensureCapabilitiesWired;
+    private currentCloudStatus;
+    private broadcastCloudStatus;
+    private sendCloudStatusToMiniapp;
+    /**
+     * Forward a streamed event to all miniapps subscribed to the given stream.
+     *
+     * Event name translation:
+     * - Cloud sends "head_up" → miniapp protocol uses "head_position" (HEAD_POSITION)
+     * - Cloud sends "VAD" (uppercase) → miniapp protocol uses "vad" (lowercase)
+     */
+    forwardEvent(streamType: string, data: unknown, transcriptionSource?: TranscriptionEventSource): void;
+    /**
+     * Persist a final utterance into the shared memory timeline when the user
+     * has "remember conversations" on (Settings > Memory).
+     *
+     * Both transcription and translation streams feed this. For translation we
+     * store `originalText` — what was actually SPOKEN — not the translated
+     * `text`: the timeline records what happened around the user, and a
+     * translation-only session (a conversation across a language barrier) would
+     * otherwise leave no trace at all. MemoryEntry carries a single text +
+     * language, so the translated variant has nowhere to live; capturing the
+     * source keeps translation- and transcription-driven sessions consistent.
+     *
+     * Only finals are stored — interims are superseded within the same utterance
+     * and would bloat the timeline with partial text. Writes are fire-and-forget
+     * and debounced inside MemoryStore, so this stays off the fan-out hot path.
+     *
+     * Runs ONCE per produced event, above the per-subscriber fan-out loop — so
+     * route selection and wildcard stream matching (which live inside that loop)
+     * can't double-write. A miniapp subscribing to both transcription AND
+     * translation for the same speech would produce two events, but nothing does
+     * that today; if that changes, suppress it at the subscription level rather
+     * than filtering on text down here, which would also drop genuine repeats.
+     */
+    private captureTranscriptToMemory;
+    private appTranscriptionRoutesForSubscription;
+    private appTranscriptionRoutesForEvent;
+    /**
+     * Translate cloud event names to miniapp stream type values.
+     */
+    private normalizeStreamType;
+    /**
+     * Send a payload to a connected miniapp, wrapped in an envelope.
+     */
+    /**
+     * Push a speaker-state transition to the owning miniapp. Idempotent: if
+     * the new state matches the cached one (and isn't an error), no envelope
+     * is sent. Error events are always sent — they're transient and the SDK
+     * settles back to a non-error state immediately after.
+     */
+    private setSpeakerState;
+    private sendToMiniapp;
+    /**
+     * Send a REQUEST_RESULT response.
+     */
+    /** Max serialized size of an action call's params / result (256 KB). */
+    private static readonly ACTION_PAYLOAD_CAP;
+    /** Outstanding action invocations, keyed by host-generated callId. */
+    private actionCalls;
+    private actionCallSeq;
+    private interopApps;
+    private isSystemPackage;
+    private startInteropApp;
+    private stopInteropApp;
+    private wakeInteropApp;
+    /** Emit an interop audit event (best-effort — never let telemetry break a call). */
+    private auditInterop;
+    /** Reject the request with NOT_PERMITTED unless the caller is a system app. */
+    private requireSystemCaller;
+    /** Project a host ClientApp into the SDK's MiniappInfo shape (JSON over the wire). */
+    private buildMiniappInfo;
+    private handleMiniappsList;
+    private handleMiniappsStart;
+    /**
+     * Self-stop (session.miniapps.stopSelf) — an app may always stop itself, so
+     * no system gate. One-shot: no reply, the caller's context is going away.
+     */
+    private handleMiniappStopSelf;
+    private handleMiniappsStop;
+    /**
+     * session.actions.list → every action the caller may invoke across installed
+     * miniapps (the MCP tools/list analog). Open to all miniapps: rows are
+     * compatibility-filtered, exclude the caller's own actions, and only include
+     * `visibility: "system"` actions for system/dev callers.
+     */
+    private handleActionsList;
+    /**
+     * session.system.exit → stop the calling miniapp itself. The result is sent
+     * before the stop so the SDK's pending request resolves rather than dying
+     * with the JS context (delivery is best-effort — the context is about to go).
+     */
+    private handleSystemExit;
+    /** True iff `value` serializes larger than the action payload cap. */
+    private actionPayloadTooLarge;
+    /**
+     * session.actions.invoke → wake the target headlessly, deliver an ACTION_CALL,
+     * and correlate its ACTION_RESULT back to the caller's pending request.
+     */
+    private handleActionInvoke;
+    /** Target → host: forward an ACTION_RESULT back to the caller's pending invoke. */
+    private handleActionResult;
+    private sendResult;
+    /**
+     * Send a VISIBILITY_CHANGE push to a miniapp.
+     */
+    sendVisibilityChange(packageName: string, visibility: "foreground" | "background"): void;
+    /**
+     * Fast foreground liveness check used when a local miniapp UI is opened or
+     * resumed. The normal watchdog intentionally waits ~30s to avoid killing a
+     * healthy-but-busy background script. When the user is actively looking at a
+     * WebView, a stale JSContext reads as "cloud offline" / no captions, so probe
+     * immediately and reuse the crash-respawn path if no message comes back.
+     */
+    probeForegroundLiveness(packageName: string, reason?: string, timeoutMs?: number): void;
+    private ensurePingLoop;
+    private stopPingLoop;
+    private doPingRound;
+    /**
+     * Called when a PONG is received from a miniapp (or any message, really).
+     * Updates lastPongAt to keep the app alive.
+     */
+    handlePong(packageName: string): void;
+    private clearForegroundProbe;
+    cleanup(): void;
+    /**
+     * Number of currently connected miniapps (for diagnostics).
+     */
+    get connectedAppCount(): number;
+}
+declare const localMiniappRuntime: LocalMiniappRuntime;
+export default localMiniappRuntime;
+//# sourceMappingURL=LocalMiniappRuntime.d.ts.map