@ateam-ai-mobile/plugin-runtime 0.1.20 → 0.1.21

package/src/sdk/types.ts

@@ -6,6 +6,7 @@
  */
 import type { DeviceState, DeviceBridgeDomain } from './device-state';
 import type { VoiceAPI } from './voice';
+import type { AiLiveAPI } from './aiLive';
 
 // ── Plugin Context ──────────────────────────────────────────
 
@@ -258,11 +259,16 @@ export interface BluetoothDevice {
 //   deviceState.visual.getSnapshot()  → "is there a current frame, how old"
 //   native.vision.readText(frame)     → "what does the sign say"
 //
-// FRAMES NEVER LEAVE THE PHONE. That is Arie's decision (2026-08-15) and it is
-// the whole reason this is a platform capability rather than an API call from
-// a plugin: analysis runs on-device, so there is no per-frame cost and no image
-// on anyone's server. An implementation that POSTs the frame somewhere would
-// satisfy the types and violate the design.
+// FRAMES STAY ON THE PHONE UNLESS TWO PEOPLE SAY YES. Arie's decision
+// (2026-08-15: frames never leave the phone) is the default and the reason this
+// is a platform capability rather than an API call from a plugin: analysis runs
+// on-device, so there is no per-frame cost and no image on anyone's server.
+// Amended 2026-10-25: a picture MAY leave only when the solution's developer
+// declares `picturesToAi` AND the person on the phone allowed it in the host's
+// settings. `mayPicturesLeavePhone()` (host.ts) is the one check; any path that
+// sends a picture off the phone must call it and refuse when it says no. No
+// such path exists yet. An implementation that POSTs a frame without that check
+// would satisfy the types and violate the design.
 //
 // IT TAKES A HANDLE, NOT PIXELS. `MediaHandle.id` from a VisualFrameRef — the
 // core rule that media crosses by reference. A plugin never holds bytes.
@@ -595,6 +601,11 @@ export interface NativeCapabilities {
   nfc?: boolean;
   /** Real biometric auth (Face ID / Touch ID / fingerprint). */
   biometricsV2?: boolean;
+  /** The developer's half of "camera pictures may go to an AI service off the
+   *  phone". Declaring it grants nothing by itself: the person on the phone must
+   *  also allow it in the host's settings. Both are checked together by
+   *  `mayPicturesLeavePhone()`. Not declared = pictures never leave. */
+  picturesToAi?: boolean;
 }
 
 // ── Lifecycle hooks ─────────────────────────────────────────
@@ -677,6 +688,14 @@ export interface PluginProps {
    * plugin gets a refusal (reads say so, actions throw) — never a fake `idle`.
    */
   voice: VoiceAPI;
+  /**
+   * The workspace's CHOSEN AI watching the phone camera, live — gated to plugins
+   * that declared `capabilities: { picturesToAi: true }` AND used only when the
+   * person on the phone allowed "Pictures to AI". The screen gets episodes
+   * ("drinking" started), never pictures; "Sending to AI" is platform-owned.
+   * REQUIRED like `voice`: an undeclared plugin gets a refusal, never a fake idle.
+   */
+  aiLive: AiLiveAPI;
   theme: ThemeTokens;
   context: PluginContext;
   /** Engine-supplied props from `sys.focusUiPlugin(pluginId, props)`.