@glassly/miniapp 0.3.0-dev.1

package/src/index.ts

@@ -0,0 +1,216 @@
+/**
+ * @glassly/miniapp — SDK for building Glassly local miniapps.
+ *
+ * Public entry point. Consumers do:
+ *
+ *   import {MiniappSession} from "@glassly/miniapp"            // background JSContext
+ *   import {useColorScheme} from "@glassly/miniapp/react"      // UI WebView hooks
+ *   import {MiniappRequestType} from "@glassly/miniapp/protocol"
+ */
+
+import {installDevReloadListenerIfDevMode} from "./dev-reload"
+
+// Auto-install the dev-reload listener on module import so authors get live
+// reload for free in dev builds. No-op in production (gated on
+// window.Glassly.miniappDeveloperMode).
+installDevReloadListenerIfDevMode()
+
+export {MiniappSession, NotConnectedError} from "./session"
+export type {
+  AuthUpdatePayload,
+  ConnectAckPayload,
+  DisplayCapabilities,
+  GlassesCapabilities,
+  MiniappAuthState,
+  MiniappRequestError,
+  MiniappSessionOptions,
+  MiniappVisibility,
+} from "./session"
+export type {AuthFetchOptions, AuthModule} from "./modules/auth"
+
+export {makeRequestId, parseEnvelope, serializeEnvelope} from "./envelope"
+export type {MiniappEnvelope} from "./envelope"
+
+export {getGlasslyGlobals} from "./globals"
+export type {GlasslyGlobals, MiniappCapsuleMenuRect, MiniappColorScheme, MiniappSafeAreaInsets} from "./globals"
+
+export {MiniappErrorCode, MiniappRequestType, MiniappResponseType, MiniappStreamType} from "./protocol"
+export {CLOUD_STATUS_STREAM} from "./modules/cloud"
+
+// Language registry (issue 021): canonical language types + the validation
+// error the typed transcription/translation surfaces throw.
+export {
+  MiniappValidationError,
+  SUPPORTED_LANGUAGE_HINTS,
+  SUPPORTED_TRANSCRIPTION_LANGUAGES,
+  isTranscriptionLanguage,
+} from "./modules/languages"
+export type {LanguageHint, TranscriptionLanguage} from "./modules/languages"
+export type {CloudClientAudioTransport, CloudClientConnectionStatus, CloudClientStatus} from "./modules/cloud"
+
+// Hardware requirement types — canonical defs live in ./hardware; miniapp
+// authors type their miniapp.json manifest with these, and @glassly/engine
+// re-exports them. Keep explicit exports (enums as value, interfaces as
+// type) for Bun compat.
+export {HardwareType, HardwareRequirementLevel} from "./hardware"
+export type {HardwareRequirement} from "./hardware"
+
+// Transports — exported for advanced uses (forced transport injection, tests)
+export {createTransport} from "./transport/auto"
+export type {CreateTransportOptions} from "./transport/auto"
+export {PostMessageTransport} from "./transport/postmessage"
+export {LocalSocketTransport} from "./transport/local-socket"
+export type {LocalSocketTransportOptions} from "./transport/local-socket"
+export {MockTransport, isMockExplicitlyRequested} from "./transport/mock"
+export type {MockTransportOptions} from "./transport/mock"
+export type {Transport, TransportDisconnectHandler, TransportMessageHandler} from "./transport/types"
+
+// Module types — useful for typing handlers in consumer code
+export type {
+  DisplayBreakMode,
+  NativeNavInfo,
+  NativeNavResult,
+  RenderBox,
+  RenderElement,
+  RenderOptions,
+  RenderRectStyle,
+  RenderResult,
+  RenderTextStyle,
+  ViewType,
+} from "./modules/display"
+export type {
+  AccelData,
+  AudioChunkData,
+  BatteryData,
+  ButtonPressData,
+  ConnectionData,
+  HeadingData,
+  HeadPositionData,
+  LocationData,
+  NotificationDismissedData,
+  PhoneNotificationData,
+  TouchData,
+  TranscriptionData,
+  TranslationData,
+  UnsubscribeFn,
+  VadData,
+  WifiData,
+} from "./modules/events"
+export type {CalendarEvent, CalendarListOptions, CalendarListResult} from "./modules/phone"
+export type {
+  PlayAudioOptions,
+  SpeakOptions,
+  SpeakResult,
+  SpeakerState,
+  SpeakerStateEvent,
+  SpeakerStreamOptions,
+  SpeakerStreamSampleRate,
+  SpeakerStreamWriteResult,
+} from "./modules/speaker"
+export {SpeakerStreamWriter, SPEAKER_STREAM_MAX_BUFFERED_MS, SPEAKER_WRITE_CHUNK_BYTES} from "./modules/speaker"
+export type {
+  CameraFovPreset,
+  CameraFovRequest,
+  CameraFovResult,
+  CameraRoiPosition,
+  PhotoTaken,
+  SetCameraFovOptions,
+  StartVideoRecordingOptions,
+  StopVideoRecordingOptions,
+  TakePhotoOptions,
+  VideoRecordingStarted,
+} from "./modules/camera"
+export type {DashboardMode, ShowNativeDashboardResult} from "./modules/dashboard"
+export type {CloudModule} from "./modules/cloud"
+export type {LedColor, LedControlOptions} from "./modules/led"
+export type {
+  RestreamDestination,
+  StartStreamOptions,
+  StreamAudioConfig,
+  StreamResolvedConfig,
+  StreamResult,
+  StreamStatus,
+  StreamVideoConfig,
+} from "./modules/stream"
+export type {
+  ShareOptions,
+  ShareResult,
+  DownloadOptions,
+  DownloadResult,
+  ScanQrOptions,
+  ScanQrResult,
+} from "./modules/system"
+export type {MiniappInfo, MiniappActionInfo, MiniappCompatibility, ListMiniappsOptions} from "./modules/miniapps"
+export type {ActionContext, ActionDescriptor, ActionHandler, InvokeOptions} from "./modules/actions"
+
+// Domain module types — exported so consumers can type module references
+// (rare; most authors interact via session.<module>.<method> directly).
+export type {DisplayManager} from "./modules/display"
+export type {MiniappsModule} from "./modules/miniapps"
+export type {ActionsModule} from "./modules/actions"
+export type {GlassesModule} from "./modules/glasses"
+export type {HeadingModule} from "./modules/heading"
+export type {
+  AiModule,
+  AiProvider,
+  AiTier,
+  AiTool,
+  AiToolCall,
+  AiToolResult,
+  AiMessage,
+  AiCompleteRequest,
+  AiCompleteResult,
+  AiStopReason,
+  AiUsage,
+} from "./modules/ai"
+export type {ImuModule} from "./modules/imu"
+export type {InputModule} from "./modules/input"
+export type {KeysModule, ApiKeyProvider} from "./modules/keys"
+export type {LocationModule} from "./modules/location"
+export type {
+  MemoryModule,
+  MemoryEntry,
+  MemoryEntryKind,
+  MemoryNoteSource,
+  MemoryQuery,
+  MemorySearchResult,
+  MemorySession,
+  MemorySummary,
+} from "./modules/memory"
+export type {SpeakersModule} from "./modules/speakers"
+export type {MicModule} from "./modules/mic"
+export type {
+  ComputedRoute,
+  ComputedRouteStep,
+  ComputeRouteOptions,
+  ComputeRouteResult,
+  LatLng,
+  NavArrived,
+  NavCancelled,
+  NavError,
+  NavigationModule,
+  NavManeuver,
+  NavOffRoute,
+  NavPermissionResult,
+  NavPlaceDetails,
+  NavPlaceSuggestion,
+  NavRerouting,
+  NavRoute,
+  NavState,
+  NavStep,
+  NavUpdate,
+  Pivot,
+  PivotEvent,
+  PivotOptions,
+  RouteAvoidances,
+  StartNavigationOptions,
+  TravelMode,
+} from "./modules/navigation"
+export type {PermissionsModule, PermissionErrorEvent} from "./modules/permissions"
+export type {PhoneModule, PhoneNotificationsModule, PhoneCalendarModule} from "./modules/phone"
+export type {TranscriptionModule, TranscriptionConfig, TranscriptionOptions} from "./modules/transcription"
+export type {TranslationModule} from "./modules/translation"
+export type {SpeakerModule} from "./modules/speaker"
+
+// Permission types
+export type {PermissionType, PermissionRecord} from "./session"

package/src/modules/actions.ts

@@ -0,0 +1,189 @@
+/**
+ * @fileoverview ActionsModule — `session.actions`.
+ *
+ * The MCP-shaped capability layer (miniapp tools), all three directions:
+ *   - `list()` — discover every action the caller may invoke across installed
+ *     miniapps (the MCP tools/list analog).
+ *   - `invoke(pkg, actionId, params)` — call another miniapp's declared action.
+ *     Open to all miniapps; headless-wakes the target if it's stopped. Actions
+ *     declared with `visibility: "system"` stay restricted to system apps.
+ *   - `handle(actionId, fn)` — expose one of your own actions. Mirrors
+ *     `session.ui.handle` (one handler per id, throws on double-register,
+ *     errors propagate to the caller).
+ *
+ * `invoke` ↔ `handle` are the two ends of one wire (keyed by `actionId`), which
+ * is why they share this namespace rather than being split across
+ * `session.miniapps` (whose lifecycle surface stays SYSTEM-only).
+ */
+
+import {MiniappErrorCode, MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+
+/** Context handed to an action handler. `callerPackageName` is host-stamped. */
+export interface ActionContext {
+  /** The package that invoked this action (trustworthy — set by the host). */
+  callerPackageName: string
+}
+
+export type ActionHandler = (params: Record<string, unknown>, ctx: ActionContext) => unknown | Promise<unknown>
+
+export interface InvokeOptions {
+  /** Overall timeout in ms (default 30s, max 120s — host-enforced). */
+  timeoutMs?: number
+}
+
+/**
+ * One invokable action surfaced by {@link ActionsModule.list}. Maps 1:1 onto
+ * an MCP tool: `id`→name, `description`, `parameters`→inputSchema.
+ */
+export interface ActionDescriptor {
+  /** The miniapp that declares (and handles) the action. */
+  packageName: string
+  /** Human-readable name of that miniapp. */
+  appName: string
+  id: string
+  description: string
+  /** JSON-Schema input descriptor (the MCP-compatible subset). */
+  parameters?: Record<string, unknown>
+  /** JSON-Schema descriptor for the structured result. */
+  outputSchema?: Record<string, unknown>
+}
+
+interface BufferedCall {
+  callId: string
+  params: Record<string, unknown>
+  ctx: ActionContext
+  timer: ReturnType<typeof setTimeout>
+}
+
+/**
+ * How long the SDK holds an inbound ACTION_CALL waiting for its handler to
+ * register (a just-woken miniapp registers handlers a beat after CONNECT).
+ * If no handler appears in this window the call is failed with
+ * NO_ACTION_HANDLER. Mirrors the UI bus's pre-handler buffering.
+ */
+const HANDLER_WAIT_MS = 5_000
+
+export class ActionsModule {
+  private readonly handlers = new Map<string, ActionHandler>()
+  /** Inbound calls buffered until their handler registers, keyed by actionId. */
+  private readonly buffered = new Map<string, BufferedCall[]>()
+
+  constructor(private readonly session: MiniappSession) {}
+
+  /**
+   * List every action this miniapp may invoke across installed miniapps.
+   * Incompatible apps and the caller's own actions are excluded; actions
+   * declared `visibility: "system"` only appear for system callers.
+   */
+  list(): Promise<ActionDescriptor[]> {
+    return this.session.sendRequest<ActionDescriptor[]>({
+      type: MiniappRequestType.ACTIONS_LIST,
+    })
+  }
+
+  /**
+   * Invoke a declared action on another miniapp. Resolves with the handler's
+   * return value, rejects with a MiniappRequestError (NOT_PERMITTED,
+   * APP_NOT_FOUND, ACTION_NOT_FOUND, WAKE_FAILED, NO_ACTION_HANDLER,
+   * ACTION_TIMEOUT, PAYLOAD_TOO_LARGE, or the handler's own error). Open to
+   * all miniapps; the target keeps running after the call — a target that
+   * wants to shut down when done can call `session.system.exit()` itself.
+   */
+  invoke<TResult = unknown>(
+    packageName: string,
+    actionId: string,
+    params?: Record<string, unknown>,
+    opts?: InvokeOptions,
+  ): Promise<TResult> {
+    return this.session.sendRequest<TResult>({
+      type: MiniappRequestType.ACTION_INVOKE,
+      targetPackageName: packageName,
+      actionId,
+      params: params ?? {},
+      ...(opts?.timeoutMs != null ? {timeoutMs: opts.timeoutMs} : {}),
+    })
+  }
+
+  /**
+   * Register a handler for one of this miniapp's declared actions. One handler
+   * per actionId — throws synchronously on double-register. The returned
+   * function unregisters. Declare the action in `miniapp.json` for it to be
+   * invokable; an undeclared id still registers but the host never routes to it.
+   */
+  handle(actionId: string, handler: ActionHandler): () => void {
+    if (this.handlers.has(actionId)) {
+      throw new Error(`session.actions.handle: a handler is already registered for "${actionId}"`)
+    }
+    this.handlers.set(actionId, handler)
+
+    // Flush any calls that arrived before this handler registered.
+    const waiting = this.buffered.get(actionId)
+    if (waiting) {
+      this.buffered.delete(actionId)
+      for (const call of waiting) {
+        clearTimeout(call.timer)
+        void this.dispatch(call.callId, actionId, call.params, call.ctx)
+      }
+    }
+
+    return () => {
+      if (this.handlers.get(actionId) === handler) this.handlers.delete(actionId)
+    }
+  }
+
+  /**
+   * @internal — called by MiniappSession.handleIncoming on an ACTION_CALL.
+   * Routes to the registered handler, or buffers briefly for one to appear.
+   */
+  _deliver(callId: string, actionId: string, params: Record<string, unknown>, ctx: ActionContext): void {
+    if (this.handlers.has(actionId)) {
+      void this.dispatch(callId, actionId, params, ctx)
+      return
+    }
+    // No handler yet — buffer, and fail with NO_ACTION_HANDLER if none registers.
+    const timer = setTimeout(() => {
+      const arr = this.buffered.get(actionId)
+      if (arr) {
+        const idx = arr.findIndex((c) => c.callId === callId)
+        if (idx >= 0) arr.splice(idx, 1)
+        if (arr.length === 0) this.buffered.delete(actionId)
+      }
+      this.sendResult(callId, false, undefined, {
+        code: MiniappErrorCode.NO_ACTION_HANDLER,
+        message: `No handler registered for action "${actionId}"`,
+      })
+    }, HANDLER_WAIT_MS)
+    const arr = this.buffered.get(actionId) ?? []
+    arr.push({callId, params, ctx, timer})
+    this.buffered.set(actionId, arr)
+  }
+
+  private async dispatch(
+    callId: string,
+    actionId: string,
+    params: Record<string, unknown>,
+    ctx: ActionContext,
+  ): Promise<void> {
+    const handler = this.handlers.get(actionId)
+    if (!handler) return
+    try {
+      const result = await handler(params, ctx)
+      this.sendResult(callId, true, result ?? null)
+    } catch (e) {
+      this.sendResult(callId, false, undefined, {
+        code: MiniappErrorCode.INTERNAL,
+        message: (e as Error)?.message ?? "action handler threw",
+      })
+    }
+  }
+
+  private sendResult(callId: string, ok: boolean, result?: unknown, error?: {code: string; message: string}): void {
+    this.session.sendOneShot({
+      type: MiniappRequestType.ACTION_RESULT,
+      callId,
+      ok,
+      ...(ok ? {result} : {error}),
+    })
+  }
+}

package/src/modules/ai.ts

@@ -0,0 +1,281 @@
+/**
+ * @fileoverview AiModule — run LLM completions through the platform.
+ *
+ * A miniapp that declares the AI permission in miniapp.json can call
+ * {@link AiModule.complete}; the phone runtime rejects with
+ * PERMISSION_NOT_DECLARED otherwise.
+ *
+ * WHY GO THROUGH THE PLATFORM instead of calling a provider directly with a key
+ * from `session.keys.get()`: the miniapp ships no API key, the platform picks
+ * and pays for the provider, and usage is metered so it can count against a
+ * plan. When the user HAS saved their own key for the resolved provider the
+ * platform uses that instead and the call is not metered — `billedToUserKey`
+ * on the result says which happened.
+ *
+ * PROVIDER-NEUTRAL — deliberately more so than before: a miniapp cannot name a
+ * provider or model at all. It states how much model the call deserves via
+ * `tier`, and the HOST resolves that to a provider+model (the user's per-tier
+ * dropdown in Settings > AI Models, or an automatic pick from whichever keys
+ * they saved). Vendor differences (system prompt placement, JSON mode,
+ * tool-schema dialect, tool-call ids) are absorbed below the session API.
+ *
+ * DELIBERATELY NOT SUPPORTED on complete(): streaming, and provider
+ * server-side tools other than web search (Anthropic `code_execution` /
+ * Files API) — complete() stays provider-neutral. Web search IS supported,
+ * as the single neutral `webSearch` flag: a capability grant the serving
+ * provider maps to its own search tool (or ignores when it has none — see
+ * the field's doc).
+ *
+ * generate() is the one sanctioned exception: an agentic visual-generation
+ * call where the CLOUD runs a provider loop with server-side tools (web
+ * search, code execution, file retrieval) and returns text plus rendered
+ * images. Anthropic-only by design, long-running (up to ~2.5 min), and
+ * markedly more expensive than a completion — call it deliberately.
+ */
+
+import {MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+
+/** Providers the platform can route to. Reported on results; never requested. */
+export type AiProvider = "anthropic" | "gemini" | "openai"
+
+/**
+ * How much model a call deserves. The host maps each tier to a concrete
+ * provider+model (Settings > AI Models); a miniapp never names either.
+ *  - quick: high-volume gating/classification where latency and cost dominate.
+ *  - balanced: routine generation (summaries, extraction).
+ *  - frontier: the user-facing answer where quality dominates.
+ */
+export type AiTier = "quick" | "balanced" | "frontier"
+
+/** A tool the MINIAPP executes. The platform never runs these. */
+export interface AiTool {
+  name: string
+  description: string
+  /**
+   * JSON Schema for the arguments, lowercase dialect (`"object"`, `"string"`).
+   * Gemini's uppercase OpenAPI dialect is translated server-side.
+   */
+  inputSchema: Record<string, unknown>
+}
+
+/** A model-issued tool call for the miniapp to execute. */
+export interface AiToolCall {
+  /** Echo this back verbatim on the matching result — never reorder or invent ids. */
+  id: string
+  name: string
+  input: Record<string, unknown>
+}
+
+/** The miniapp's answer to one {@link AiToolCall}. */
+export interface AiToolResult {
+  toolCallId: string
+  /** Serialized result — JSON.stringify structured data yourself. */
+  content: string
+  /** True when the tool failed, so the model can recover rather than hang. */
+  isError?: boolean
+}
+
+/** One conversation turn. */
+export interface AiMessage {
+  role: "user" | "assistant"
+  content: string
+  /** Present on an assistant turn the model paused on to call tools. */
+  toolCalls?: AiToolCall[]
+  /** Present on a user turn answering those calls. */
+  toolResults?: AiToolResult[]
+}
+
+export interface AiCompleteRequest {
+  messages: AiMessage[]
+  system?: string
+  /** Model tier for this call. Omitted means "balanced". */
+  tier?: AiTier
+  maxTokens?: number
+  /** Advisory: providers whose current models reject sampling params drop it. */
+  temperature?: number
+  /** Ask for a JSON object back. You still parse and validate the text. */
+  jsonMode?: boolean
+  tools?: AiTool[]
+  /**
+   * Let the model search the web when live data would help. A GRANT, not a
+   * command: the model may answer from knowledge, and providers without a
+   * server-side search tool (currently OpenAI) ignore the flag. Searches run
+   * inside the same call — no extra round-trip, no tool loop on your side —
+   * and `webSearchCount` on the result reports how many actually ran.
+   * Platform-funded searches cost a small per-search surcharge on top of
+   * tokens.
+   */
+  webSearch?: boolean
+}
+
+/**
+ * Why the model stopped. `refusal` is a SUCCESSFUL result (the model declined),
+ * not an error — check it before trusting `text`.
+ */
+export type AiStopReason = "end_turn" | "tool_use" | "max_tokens" | "refusal"
+
+export interface AiUsage {
+  inputTokens: number
+  outputTokens: number
+}
+
+export interface AiCompleteResult {
+  /** Concatenated text. Empty when the model only called tools. */
+  text: string
+  stopReason: AiStopReason
+  /** Populated iff `stopReason === "tool_use"`. */
+  toolCalls?: AiToolCall[]
+  usage: AiUsage
+  provider: AiProvider
+  model: string
+  /** True when the user's own key paid for this call, so it wasn't metered. */
+  billedToUserKey: boolean
+  /**
+   * Server-side web searches the model ran (see `webSearch` on the request).
+   * Absent/0 when search wasn't granted, the provider has none, or the model
+   * answered from knowledge.
+   */
+  webSearchCount?: number
+}
+
+/** Internal event stream carrying generate() progress ticks from the host. */
+const AI_GENERATE_PROGRESS_STREAM = "_ai_generate_progress"
+
+/** LLM calls take far longer than the 60s default request timeout. */
+const AI_REQUEST_TIMEOUT_MS = 120_000
+/** Generation runs an agentic loop server-side (~150s wall-clock budget). */
+const AI_GENERATE_TIMEOUT_MS = 180_000
+
+/** Request for one agentic visual-generation run. One shot — no conversation. */
+export interface AiGenerateRequest {
+  /** The task. Include any data and display constraints the artist needs. */
+  prompt: string
+  /** Extra system guidance appended to the platform's base artist prompt. */
+  system?: string
+  /** Provider-specific model id. Omit for the platform's generate default. */
+  model?: string
+  maxTokens?: number
+  /** Agentic round budget; the platform clamps to its own ceiling. */
+  maxRounds?: number
+}
+
+/**
+ * A coarse progress tick from a running generate() call. `activity` is one of
+ * "thinking" | "searching" | "drawing" | "finishing" today, but treat unknown
+ * values as "thinking" — the platform may refine labels without a new SDK.
+ */
+export interface AiGenerateProgress {
+  activity: string
+}
+
+/** One rendered image, ready for `session.display.render`-style consumption. */
+export interface AiGeneratedImage {
+  /** Base64 image bytes (no data: prefix). */
+  data: string
+  mimeType: string
+  width?: number
+  height?: number
+}
+
+export interface AiGenerateResult {
+  /** Final text (caption/answer). May be empty if the model only drew. */
+  text: string
+  images: AiGeneratedImage[]
+  stopReason: AiStopReason
+  usage: AiUsage & {rounds: number}
+  provider: AiProvider
+  model: string
+  billedToUserKey: boolean
+}
+
+export class AiModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  /** True iff `AI` is declared in the miniapp's manifest. */
+  get hasPermission(): boolean {
+    return this.session._hasManifestPermission("AI")
+  }
+
+  /**
+   * Run one completion turn.
+   *
+   * For a tool loop: call, and if `stopReason === "tool_use"`, append an
+   * assistant turn carrying `toolCalls` plus a user turn carrying your
+   * `toolResults`, then call again. Bound your own loop — the platform holds no
+   * conversation state, so nothing else will stop a runaway.
+   */
+  async complete(request: AiCompleteRequest): Promise<AiCompleteResult> {
+    return this.session.sendRequest<AiCompleteResult>(
+      {type: MiniappRequestType.AI_COMPLETE, ...request},
+      {timeoutMs: AI_REQUEST_TIMEOUT_MS},
+    )
+  }
+
+  /**
+   * Run one agentic visual-generation call. The cloud drives a provider loop
+   * with server-side web search + code execution and returns text plus any
+   * rendered images. Expect tens of seconds of latency — show progress UI.
+   * Rejects with QUOTA_EXCEEDED when the account's AI credit is spent, and
+   * with INTERNAL naming an HTTP status when the host predates this request
+   * type or the cloud has the surface disabled.
+   *
+   * `onProgress` receives coarse activity ticks ("searching", "drawing", …)
+   * while the run is in flight, so a caller can keep a wait card honest.
+   * Best-effort: hosts/clouds that predate the progress surface complete the
+   * call normally and just never tick.
+   */
+  async generate(
+    request: AiGenerateRequest,
+    opts: {onProgress?: (progress: AiGenerateProgress) => void} = {},
+  ): Promise<AiGenerateResult> {
+    const onProgress = opts.onProgress
+    if (!onProgress) {
+      return this.session.sendRequest<AiGenerateResult>(
+        {type: MiniappRequestType.AI_GENERATE, ...request},
+        {timeoutMs: AI_GENERATE_TIMEOUT_MS},
+      )
+    }
+
+    // Correlate progress events to THIS call via a caller-minted token the
+    // host echoes back on the internal `_ai_generate_progress` stream —
+    // internal streams ride the local fan-out and never hit SUBSCRIBE.
+    const progressToken = `gen-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
+    const unsubscribe = this.session.events.subscribe(AI_GENERATE_PROGRESS_STREAM, (data) => {
+      const tick = data as {progressToken?: string; activity?: string} | undefined
+      if (tick?.progressToken !== progressToken || typeof tick.activity !== "string") return
+      try {
+        onProgress({activity: tick.activity})
+      } catch {
+        // A throwing listener must not break the generation promise chain.
+      }
+    })
+    try {
+      return await this.session.sendRequest<AiGenerateResult>(
+        {type: MiniappRequestType.AI_GENERATE, ...request, progressToken},
+        {timeoutMs: AI_GENERATE_TIMEOUT_MS},
+      )
+    } finally {
+      unsubscribe()
+    }
+  }
+
+  /**
+   * Convenience for the common single-shot case: one prompt in, text out.
+   * Throws when the model refused, so callers that just want a string don't
+   * have to remember that a refusal arrives as a success.
+   */
+  async prompt(
+    prompt: string,
+    opts: {system?: string; maxTokens?: number; jsonMode?: boolean; tier?: AiTier} = {},
+  ): Promise<string> {
+    const result = await this.complete({
+      messages: [{role: "user", content: prompt}],
+      ...opts,
+    })
+    if (result.stopReason === "refusal") {
+      throw new Error("the model declined to answer this prompt")
+    }
+    return result.text
+  }
+}