@glassly/engine 0.1.0-dev.0

package/src/runtime/config.ts

@@ -0,0 +1,155 @@
+/**
+ * Runtime-shared constants and DTOs.
+ *
+ * The old host-injected runtime adapter surface has moved behind engine-owned
+ * services and `engine.configure({auth, config, analytics})`. Keep this file
+ * limited to stable types that are shared across those services.
+ */
+
+export type CloudClientConnectionStatus = "connected" | "connecting" | "reconnecting" | "disconnected"
+export type CloudClientAudioTransport = "udp" | "ws" | "offline" | "none"
+
+export interface CloudClientStatusSnapshot {
+  status: CloudClientConnectionStatus
+  audioTransport: CloudClientAudioTransport
+}
+
+export interface MiniappAuthToken {
+  glasslyUserId: string
+  tenantId?: string
+  token: string
+  expiresAt: number
+}
+
+/**
+ * Result of an offline TTS synthesis. The engine's TTSModelManager produces
+ * this directly; the type is kept exported for hosts that wrap it.
+ */
+export interface TtsSynthesisResult {
+  audioUrl: string
+  cleanup?: () => Promise<void> | void
+}
+
+/**
+ * Stable settings keys read by engine services. Hosts must wire their own
+ * settings store keys to these names. Mobile already uses these strings.
+ */
+export const ISLAND_SETTINGS_KEYS = {
+  localSttFallbackActive: "local_stt_fallback_active",
+  localSttFallbackReason: "local_stt_fallback_reason",
+  defaultWearable: "default_wearable",
+  coreToken: "core_token",
+  cameraFov: "camera_fov",
+} as const
+
+/**
+ * Navigation event payloads. Mirror the host's NavigationService types but are
+ * duplicated here so the engine module does not import host types.
+ */
+export type NavManeuverEvent = {
+  kind: "maneuver"
+  maneuverType: string
+  distanceMeters: number
+  fromRoad?: string | null
+  toRoad?: string | null
+  nextStepRoad?: string | null
+  distanceToDestinationMeters?: number
+  timeToDestinationSeconds?: number
+  currentSpeedMps?: number | null
+  speedLimitMps?: number | null
+  routeHeadingDeg?: number | null
+}
+export type NavOffRouteEvent = {kind: "off_route"; offRouteDistanceMeters: number}
+export type NavReroutingEvent = {kind: "rerouting"}
+export type NavArrivedEvent = {kind: "arrived"}
+export type NavErrorEvent = {kind: "error"; message: string}
+/** Synthesized by the host when the trip is cancelled outside the miniapp (e.g. wearer exited nav mode on the glasses). */
+export type NavCancelledEvent = {kind: "cancelled"; reason?: string}
+export type NavUpdate =
+  | NavManeuverEvent
+  | NavOffRouteEvent
+  | NavReroutingEvent
+  | NavArrivedEvent
+  | NavErrorEvent
+  | NavCancelledEvent
+
+export type NavLocation = {
+  lat: number
+  lng: number
+  accuracy: number | null
+  timestamp: number
+}
+
+export type NavRouteStep = {
+  lat: number
+  lng: number
+  routeIndex: number
+  road: string | null
+  maneuver: string
+  distanceMeters: number
+}
+export type NavRoute = {
+  points: Array<{lat: number; lng: number}>
+  steps?: NavRouteStep[]
+}
+
+export type NavTripSnapshot = {
+  active: boolean
+  mode?: string
+  stops?: Array<{lat: number; lng: number}>
+  currentStopIndex?: number
+  route?: NavRoute
+  maneuver?: NavManeuverEvent
+  distanceToDestinationMeters?: number
+  timeToDestinationSeconds?: number
+  currentSpeedMps?: number | null
+  speedLimitMps?: number | null
+}
+
+export interface StreamVideoConfig {
+  width?: number
+  height?: number
+  bitrate?: number
+  fps?: number
+}
+
+export interface StreamAudioConfig {
+  bitrate?: number
+  sampleRate?: number
+  echoCancellation?: boolean
+  noiseSuppression?: boolean
+}
+
+export type CameraRoiPosition = "center" | "bottom" | "top"
+export type CameraFovPreset = "narrow" | "standard" | "wide"
+
+export type CameraFovRequest =
+  | {
+      fov: number
+      roiPosition?: CameraRoiPosition
+    }
+  | {
+      preset: CameraFovPreset
+    }
+
+export interface CameraFovResult {
+  requestId: string
+  fov: number
+  roiPosition: CameraRoiPosition
+  timestamp: number
+}
+
+/** One audited inter-miniapp call. */
+export interface InteropAuditEvent {
+  /** The app that made the call. */
+  caller: string
+  op: "list" | "start" | "stop" | "invoke" | "actions_list" | "exit"
+  /** Target miniapp (start/stop/invoke). */
+  target?: string
+  /** Action id (invoke only). */
+  actionId?: string
+  /** True if the call was permitted and accepted; false on denial / pre-flight failure. */
+  ok: boolean
+  /** MiniappErrorCode when ok is false. */
+  errorCode?: string
+}

package/src/runtime/scanQrSeam.ts

@@ -0,0 +1,20 @@
+import type {ScanQrOptions, ScanQrResult} from "./bootstrap"
+
+export class ScanQrNotConfiguredError extends Error {
+  readonly code = "NOT_IMPLEMENTED"
+  constructor() {
+    super("QR scanning is not configured on this host. Reload the Glassly App and try again.")
+    this.name = "ScanQrNotConfiguredError"
+  }
+}
+
+export async function invokeScanQrSeam(
+  scanQr: ((options?: ScanQrOptions) => Promise<ScanQrResult>) | undefined,
+  payload: Record<string, unknown> = {},
+): Promise<ScanQrResult> {
+  if (!scanQr) throw new ScanQrNotConfiguredError()
+  return scanQr({
+    title: typeof payload.title === "string" ? payload.title : undefined,
+    hint: typeof payload.hint === "string" ? payload.hint : undefined,
+  })
+}

package/src/runtime/streamConfig.ts

@@ -0,0 +1,34 @@
+import type {StreamAudioConfig, StreamVideoConfig} from "./config"
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const finiteNumber = (value: unknown): number | undefined =>
+  typeof value === "number" && Number.isFinite(value) ? value : undefined
+
+export const normalizeStreamVideoConfig = (value: unknown): StreamVideoConfig | undefined => {
+  if (!isRecord(value)) return undefined
+  const config: StreamVideoConfig = {}
+  const width = finiteNumber(value.width)
+  const height = finiteNumber(value.height)
+  const bitrate = finiteNumber(value.bitrate)
+  const frameRate = finiteNumber(value.frameRate)
+  const fps = frameRate ?? finiteNumber(value.fps)
+  if (width !== undefined) config.width = width
+  if (height !== undefined) config.height = height
+  if (bitrate !== undefined) config.bitrate = bitrate
+  if (fps !== undefined) config.fps = fps
+  return Object.keys(config).length > 0 ? config : undefined
+}
+
+export const normalizeStreamAudioConfig = (value: unknown): StreamAudioConfig | undefined => {
+  if (!isRecord(value)) return undefined
+  const config: StreamAudioConfig = {}
+  const bitrate = finiteNumber(value.bitrate)
+  const sampleRate = finiteNumber(value.sampleRate)
+  if (bitrate !== undefined) config.bitrate = bitrate
+  if (sampleRate !== undefined) config.sampleRate = sampleRate
+  if (typeof value.echoCancellation === "boolean") config.echoCancellation = value.echoCancellation
+  if (typeof value.noiseSuppression === "boolean") config.noiseSuppression = value.noiseSuppression
+  return Object.keys(config).length > 0 ? config : undefined
+}

package/src/services/AiTierResolution.ts

@@ -0,0 +1,106 @@
+/**
+ * AiTierResolution — pure decision logic for mapping a miniapp's requested AI
+ * tier ("quick" / "balanced" / "frontier") to a concrete provider+model.
+ *
+ * Miniapps never name a provider or model (the session.ai contract is
+ * tier-only); the user picks per-tier models in Settings > AI Models, or
+ * leaves "auto" and the pick follows from whichever provider keys they saved.
+ * Extracted from LocalMiniappRuntime as pure functions so the routing rules
+ * are unit-testable (the TranscriptionRouting.ts pattern) — the singleton
+ * supplies settings/keys and does the side effects.
+ */
+
+export type AiTier = "quick" | "balanced" | "frontier"
+export type AiTierProvider = "anthropic" | "gemini" | "openai"
+
+export const AI_TIERS: readonly AiTier[] = ["quick", "balanced", "frontier"]
+
+/** One curated dropdown entry for a tier. */
+export interface TierModelOption {
+  provider: AiTierProvider
+  model: string
+  /** Human label for the Settings dropdown. */
+  label: string
+}
+
+/**
+ * Curated per-tier model registry — the only place model ids live on the
+ * phone. Order within a tier is the "auto" preference order: first entry
+ * whose provider has a saved key wins. Anthropic leads (matching the cloud's
+ * default provider), then Gemini (the pre-tier quick default), then OpenAI.
+ */
+export const TIER_MODEL_OPTIONS: Record<AiTier, TierModelOption[]> = {
+  quick: [
+    {provider: "anthropic", model: "claude-haiku-4-5", label: "Claude Haiku 4.5"},
+    {provider: "gemini", model: "gemini-3.5-flash-lite", label: "Gemini 3.5 Flash Lite"},
+    {provider: "openai", model: "gpt-5-mini", label: "GPT-5 mini"},
+  ],
+  balanced: [
+    {provider: "anthropic", model: "claude-haiku-4-5", label: "Claude Haiku 4.5"},
+    {provider: "gemini", model: "gemini-3.5-flash", label: "Gemini 3.5 Flash"},
+    {provider: "openai", model: "gpt-5.1", label: "GPT-5.1"},
+  ],
+  frontier: [
+    {provider: "anthropic", model: "claude-sonnet-5", label: "Claude Sonnet 5"},
+    {provider: "gemini", model: "gemini-3.5-pro", label: "Gemini 3.5 Pro"},
+    {provider: "openai", model: "gpt-5.1", label: "GPT-5.1"},
+  ],
+}
+
+/** Which providers currently have a user key saved (Settings > API Keys). */
+export type SavedLlmKeys = Record<AiTierProvider, boolean>
+
+/**
+ * A resolved pick. `provider`/`model` may both be absent: that means "no
+ * opinion — let the cloud's default provider serve it", which is the right
+ * answer for platform-funded balanced/frontier calls with no keys saved.
+ */
+export interface ResolvedTierModel {
+  provider?: AiTierProvider
+  model?: string
+}
+
+/** Coerce an untrusted wire value into a tier; anything else is "balanced". */
+export function normalizeAiTier(value: unknown): AiTier {
+  return value === "quick" || value === "frontier" ? value : "balanced"
+}
+
+/** Parse a stored "<provider>:<model>" dropdown value; null for "auto"/garbage. */
+export function parseTierSetting(value: unknown): {provider: AiTierProvider; model: string} | null {
+  if (typeof value !== "string") return null
+  const sep = value.indexOf(":")
+  if (sep <= 0) return null
+  const provider = value.slice(0, sep)
+  const model = value.slice(sep + 1).trim()
+  if (!model) return null
+  if (provider !== "anthropic" && provider !== "gemini" && provider !== "openai") return null
+  return {provider, model}
+}
+
+/**
+ * Resolve one tier to a provider+model.
+ *
+ * Explicit dropdown pick wins verbatim — even if that provider's key was
+ * since removed (the call falls through to the cloud path, which may serve it
+ * on the platform key or fail loudly; silently substituting a different model
+ * the user didn't pick would be worse).
+ *
+ * "auto": first curated entry whose provider has a saved key. With no keys at
+ * all, quick still pins its cheapest curated model on the cloud's Gemini key
+ * (high-volume triage on the default Sonnet would burn platform credit ~30x
+ * faster), while balanced/frontier stay unpinned and take the cloud default.
+ */
+export function resolveAiTier(tier: AiTier, settingValue: unknown, keys: SavedLlmKeys): ResolvedTierModel {
+  const explicit = parseTierSetting(settingValue)
+  if (explicit) return explicit
+
+  for (const option of TIER_MODEL_OPTIONS[tier]) {
+    if (keys[option.provider]) return {provider: option.provider, model: option.model}
+  }
+
+  if (tier === "quick") {
+    const gemini = TIER_MODEL_OPTIONS.quick.find((o) => o.provider === "gemini")
+    if (gemini) return {provider: gemini.provider, model: gemini.model}
+  }
+  return {}
+}