@ateam-ai-mobile/plugin-runtime 0.1.5 → 0.1.7

package/src/tools/sessionSync.ts

@@ -0,0 +1,107 @@
+/**
+ * Ambient device-tool registration, driven by the auth session (R14).
+ *
+ * The LOCAL reasoning path must be live BEFORE voice opens — otherwise the only
+ * proof of a loadable external skill is a voice-triggered one. So the host wires
+ * this to its EXISTING auth-session subscription (no new transport, no plugin
+ * special-case): a tenant becoming authenticated loads that tenant's external
+ * device-tool bundles (and re-ensures the static platform tools); a tenant
+ * SWITCH is a change of tenant while still authenticated, so it clears the old
+ * tenant's tools and reloads; sign-out resets the loader latch (the registry
+ * itself is cleared by the host's logout teardown, which already calls
+ * clearDeviceTools()).
+ *
+ * The decision is a PURE function so the lifecycle is testable without a network
+ * or a device; the effects are injected (same DI shape as the host's logout
+ * teardown) so a test drives them with fakes.
+ */
+import { registerPlatformDeviceTools } from './platformTools';
+import { clearDeviceTools } from './registry';
+// NOTE: `./loader` pulls in the bundle manager (react-native, core), so it is
+// imported LAZILY inside the real effects below — keeping this module itself
+// node-testable (a test injects fake effects and never touches that graph).
+
+export interface SessionSnapshot {
+  authenticated: boolean;
+  /** The tenant the session is scoped to (derive it; never a stored copy). */
+  tenant: string | null;
+}
+
+export type DeviceToolsAction = 'load' | 'reset' | 'none';
+
+/**
+ * PURE: what should the device-tool registry do for this session transition?
+ * - a new authenticated tenant (initial sign-in OR a switch) → 'load'
+ * - the same authenticated tenant again (e.g. a silent token refresh) → 'none'
+ * - leaving authenticated (sign-out) → 'reset'
+ */
+export function deviceToolsActionForSession(
+  next: SessionSnapshot,
+  prevTenant: string | null,
+): { action: DeviceToolsAction; tenant: string | null } {
+  const tenant = next.authenticated ? (next.tenant ?? null) : null;
+  if (tenant && tenant !== prevTenant) return { action: 'load', tenant };
+  if (!tenant && prevTenant) return { action: 'reset', tenant: null };
+  return { action: 'none', tenant: prevTenant };
+}
+
+/** The effects a session transition drives — injected so a test can fake them. */
+export interface DeviceToolsSessionDeps {
+  /** Drop the previous tenant's device tools (a switch does not run logout teardown). */
+  clear: () => void;
+  /** Ensure the static, host-owned platform device tools are present. */
+  registerPlatform: () => void;
+  /** Forget the "already loaded" latch so a later (non-forced) load runs — sign-out. */
+  resetLoader: () => void;
+  /** Fire-and-forget reload of the current tenant's external device-tool bundles. */
+  load: () => void;
+}
+
+const REAL_DEPS: DeviceToolsSessionDeps = {
+  clear: clearDeviceTools,
+  registerPlatform: registerPlatformDeviceTools,
+  // `./loader` reaches react-native via the bundle manager; import it only when
+  // an effect actually fires (real app), never at module load (tests).
+  resetLoader: () => {
+    void import('./loader').then((m) => m.resetDeviceToolLoader());
+  },
+  load: () => {
+    void import('./loader').then((m) => {
+      m.resetDeviceToolLoader();
+      return m.ensureDeviceToolsLoaded({ force: true });
+    });
+  },
+};
+
+let prevTenant: string | null = null;
+
+/**
+ * Apply a session transition to the device-tool registry. Call from the host's
+ * existing auth-session subscription with a derived snapshot. Idempotent per
+ * tenant: repeated snapshots for the same authenticated tenant do nothing, so a
+ * silent token refresh does not churn the registry. Returns the action taken.
+ */
+export function syncDeviceToolsForSession(
+  next: SessionSnapshot,
+  deps: DeviceToolsSessionDeps = REAL_DEPS,
+): DeviceToolsAction {
+  const { action, tenant } = deviceToolsActionForSession(next, prevTenant);
+  prevTenant = tenant;
+  if (action === 'load') {
+    // A new authenticated tenant: drop the prior tenant's tools, re-seat the
+    // static platform tools, then reload this tenant's external bundles (forced).
+    deps.clear();
+    deps.registerPlatform();
+    deps.load();
+  } else if (action === 'reset') {
+    // Sign-out: the host's logout teardown clears the registry; we only forget
+    // the loader latch so a later sign-in reloads.
+    deps.resetLoader();
+  }
+  return action;
+}
+
+/** Test seam: forget the last-seen tenant so a test starts from signed-out. */
+export function __resetSessionSyncForTest(): void {
+  prevTenant = null;
+}

package/src/voiceHost.ts

@@ -0,0 +1,126 @@
+/**
+ * Host DI + gate for `props.voice` — the session counterpart of
+ * setDeviceStateProvider / setPluginNativeProvider.
+ *
+ * The app mounts one live voice session (VoiceSessionHost in @ateam-ai-mobile/ui)
+ * and hands it here once at startup via setVoiceProvider. gateVoice then decides,
+ * per plugin, whether that session is exposed:
+ *
+ *  - declared (`capabilities: { voice: true }`) + a provider present → the real
+ *    session.
+ *  - declared but no provider (no session host in this build) → a refusal that
+ *    names the reason.
+ *  - NOT declared → a refusal that names the reason.
+ *
+ * ABSENCE IS AN ANSWER (spec invariant 6). A denied surface never fakes an
+ * `idle` snapshot and never silently no-ops: reads report `state: 'error'` with
+ * an explicit `lastError`, and actions throw. A silent `idle` would read to a
+ * reasoning loop as "a working session that simply isn't connected yet" — a
+ * fabrication, the same class of bug as an undefined that flows into an answer.
+ */
+import type { VoiceAPI, VoiceSnapshot, VoiceSessionProvider } from './sdk/voice';
+
+let _provider: VoiceSessionProvider | null = null;
+
+/** Host DI: the app supplies its live (owner-aware) voice session. Called once
+ *  at startup; pass null to detach (e.g. in a build with no voice). */
+export function setVoiceProvider(provider: VoiceSessionProvider | null): void {
+  _provider = provider || null;
+}
+
+/** Whether this build has a voice session to expose — for diagnostics. */
+export function implementedVoice(): boolean {
+  return !!_provider;
+}
+
+function voiceDenial(why: string): Error {
+  const err: any = new Error(`voice: ${why}`);
+  // Frozen vocabulary (matches gateDeviceState): a capability/manifest gate IS a
+  // policy, so a denial is RESTRICTED — no new error vocabulary.
+  err.code = 'RESTRICTED';
+  return err;
+}
+
+/**
+ * The refused surface. Reads answer honestly ("I am not available, here is
+ * why"); actions throw. Deliberately NOT a fake `idle` and NOT a silent no-op.
+ */
+function deniedVoice(why: string): VoiceAPI {
+  const fail = () => { throw voiceDenial(why); };
+  return {
+    async start() { return fail(); },
+    stop() { fail(); },
+    setMuted() { fail(); },
+    prompt() { fail(); },
+    observe() { fail(); },
+    getSnapshot(): VoiceSnapshot {
+      return {
+        state: 'error',
+        sessionId: null,
+        muted: false,
+        speaking: false,
+        listening: false,
+        userSpeaking: false,
+        lastUserSpeechEndedAt: null,
+        lastError: why,
+      };
+    },
+    subscribe() { return fail(); },
+    transcript() { return []; },
+  };
+}
+
+/**
+ * A per-plugin VoiceAPI that stamps `pluginId` as the caller on every call, so
+ * the owner-aware provider can isolate it. TWO plugins get TWO facades bound to
+ * TWO identities; neither can read, control, or attach to the other's live
+ * session — even though both declared voice and both share the one physical
+ * session. A plugin never supplies its own identity: it is captured here.
+ */
+function scopedVoice(provider: VoiceSessionProvider, pluginId: string): VoiceAPI {
+  return {
+    start: (opts) => provider.start(opts, pluginId),
+    stop: () => provider.stop(pluginId),
+    setMuted: (muted) => provider.setMuted(muted, pluginId),
+    prompt: (input) => provider.prompt(input, pluginId),
+    observe: (text) => provider.observe(text, pluginId),
+    getSnapshot: () => provider.getSnapshot(pluginId),
+    subscribe: (cb) => provider.subscribe(cb, pluginId),
+    transcript: () => provider.transcript(pluginId),
+  };
+}
+
+/**
+ * The `voice` a plugin receives, gated by whether it declared the capability AND
+ * scoped to its identity.
+ *
+ * `declared` is `!!capabilities.voice` from the plugin's TRUSTED declaration
+ * (resolved in pluginRuntime.ts — the server manifest for a remote plugin, the
+ * registry entry for a host-owned one). A downloaded bundle cannot grant itself
+ * voice. `pluginId` is the trusted identity the returned facade is bound to.
+ *
+ * Reading the transcript of a live session is a privacy surface, not just an
+ * API: this gate is the only thing between a plugin and everything the user
+ * says. Two protections stack: (1) it is coupled to evidence — a live session
+ * shows the platform-owned, unsuppressable mic indicator, so there is no path to
+ * a transcript without visible proof the mic is/was live; and (2) it is scoped
+ * to the owner, so declaring `voice` lets a plugin run ITS OWN conversation, not
+ * eavesdrop on another solution's. A missing identity FAILS CLOSED.
+ */
+export function gateVoice(declared: boolean, pluginId: string): VoiceAPI {
+  if (!declared) {
+    return deniedVoice(
+      "not declared in this plugin's capabilities. Add `capabilities: { voice: true }` to use it.",
+    );
+  }
+  if (!pluginId) {
+    return deniedVoice(
+      'no plugin identity — voice fails closed without a caller to scope the session to.',
+    );
+  }
+  return _provider
+    ? scopedVoice(_provider, pluginId)
+    : deniedVoice(
+        'no voice session in this build — the app has not mounted a VoiceSessionHost / called setVoiceProvider.',
+      );
+}