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

package/src/bundles/integrity.ts

@@ -0,0 +1,29 @@
+/**
+ * R8 remote-bundle integrity — the fail-closed check run INLINE, immediately
+ * before a remote bundle is evaluated with `new Function`.
+ *
+ * See docs/decisions/REMOTE_BUNDLE_INTEGRITY.md for the threat model and the
+ * (declined) publisher-signature decision. This is INTEGRITY, not a sandbox:
+ * it proves the bytes about to run are exactly the ones the trusted manifest
+ * hash names; it does not isolate what they can do.
+ */
+import { sha256Hex } from '../utils/sha256';
+
+/**
+ * Refuse to evaluate a bundle whose bytes do not match the SHA-256 that
+ * gate-kept them. Fail-closed on a MISSING hash too — an unverifiable bundle is
+ * treated exactly like a mismatched one. `verifiedHash` is the manifest hash for
+ * a cache hit or the freshly-verified download hash; re-hashing `content` here
+ * closes the disk-cache-tamper gap the download-time check leaves open.
+ */
+export function assertBundleIntegrity(content: string, verifiedHash: string | null, label: string): void {
+  const digest = sha256Hex(content);
+  if (!verifiedHash) {
+    throw new Error(`[bundle-integrity] refusing to evaluate ${label}: no verified SHA-256 (fail closed).`);
+  }
+  if (digest !== verifiedHash.toLowerCase()) {
+    throw new Error(
+      `[bundle-integrity] integrity FAIL at eval for ${label}: content sha256 ${digest.slice(0, 12)}… ≠ verified ${verifiedHash.slice(0, 12)}…. Refusing to evaluate.`,
+    );
+  }
+}

package/src/bundles/storage.ts

@@ -5,6 +5,7 @@
  * default is in-memory (bundles re-download per app session — correct,
  * just slower on cold start).
  */
+import type { PluginGrants } from '../pluginRuntime';
 
 export interface BundleCacheEntry {
   localPath: string;
@@ -13,6 +14,64 @@ export interface BundleCacheEntry {
   bundleUrl: string;
   /** SHA-256 (hex, lowercase) of the cached bundle bytes — integrity proof */
   bundleHash?: string;
+  /**
+   * Tenant whose session downloaded these bytes.
+   *
+   * A bundle URL is NOT tenant-independent: `/api/ui-plugins/<id>/bundle.js`
+   * resolves per-tenant on the server, so the SAME url returns different code
+   * for different tenants. On the normal load path the hash gate catches this
+   * for free — the expected hash comes from the current tenant's manifest and
+   * will not match another tenant's cached bytes. The disk-cache recovery path
+   * has no manifest to check against, so it must discriminate by tenant.
+   *
+   * Absent on entries written before this field existed: unknown ownership, so
+   * untrusted. Never read a missing tenant as "mine".
+   */
+  tenant?: string;
+  /**
+   * The trusted declaration these bytes' device tools were last registered
+   * under: the pluginId and grants resolved from the server manifest that named
+   * this bundle (resolvePluginGrants). Recorded so the disk-cache recovery path —
+   * which runs exactly when there is NO manifest — re-registers with the same
+   * authority instead of the bundle's own claim.
+   *
+   * Absent → no trusted declaration is known for these bytes, so recovery skips
+   * the entry (fail closed) and the catalog path registers it once the owning
+   * connector answers again.
+   */
+  trusted?: TrustedToolDeclaration;
+}
+
+/** Who a bundle's device tools belong to and what they are granted — always
+ *  from the manifest, never from the bundle. */
+export interface TrustedToolDeclaration extends PluginGrants {
+  pluginId: string;
+}
+
+/**
+ * Which cached entries belong to `tenant` and may therefore be re-evaluated.
+ *
+ * Lives here, beside the entry type, so "may I run this cached code" has ONE
+ * owner rather than being re-answered by each caller. `loadIndex()` returns
+ * every entry regardless of owner — it has to, since the manager looks entries
+ * up by url and rewrites them — so any caller that EVALUATES cached code must
+ * come through this function first.
+ *
+ * Fail-closed on both unknowns. An empty tenant owns nothing. An entry with no
+ * recorded tenant has unknown ownership and is never assumed to be the current
+ * one: every device already in the field has unstamped entries, so reading
+ * "missing" as "mine" would keep the hole open exactly where it is hardest to
+ * see.
+ *
+ * Compares the tenant field directly — it never builds a composite key, so
+ * there is no separator a tenant name could forge across.
+ */
+export function selectOwnedCacheEntries<T extends { tenant?: string }>(
+  entries: T[],
+  tenant: string | null | undefined,
+): T[] {
+  if (!tenant) return [];
+  return (entries || []).filter((e) => !!e && e.tenant === tenant);
 }
 
 export interface BundleStorage {

package/src/deviceStateHost.ts

@@ -0,0 +1,222 @@
+/**
+ * Host DI for the SEMANTIC layer — the `props.deviceState` counterpart of
+ * `setPluginNativeProvider`.
+ *
+ * Kept in its own file rather than added to host.ts, for the same reason the
+ * two layers have separate namespaces: the moment they share a module, the
+ * next person adds a domain to `PluginNative` or a capability to
+ * `stateDomains` and the boundary starts to blur.
+ *
+ * THE GATE IS NOT THE MECHANICAL ONE. `gatePluginNative` replaces an
+ * undeclared capability with a proxy whose methods warn and return `undefined`
+ * — so `await native.location.getCurrent()` resolves to `undefined`, and
+ * `pos?.latitude` is `undefined`, which flows into a model answer as a
+ * confident nothing. A silent undefined is a fabrication vector.
+ *
+ * Here, an undeclared domain returns a real snapshot in which everything is
+ * explicitly `unknown` / `null`, with `freshness.state = 'unknown'`. The
+ * plugin gets a well-formed answer that says "I know nothing", which no
+ * reasonable code path can mistake for data.
+ */
+import type { DeviceBridgeDomain, DeviceState, StateQuality } from './sdk/device-state';
+
+// The `unknown` freshness/confidence shape is the canonical `neverObserved()` +
+// `{ level: 'unknown' }` (see sdk/device-state.ts). It is inlined here rather
+// than imported because this module is imported directly by node --test and the
+// harness resolves only the explicit entry, not a nested extensionless value
+// import. The golden snapshot test pins this shape === neverObserved()'s.
+const UNKNOWN_QUALITY: StateQuality = {
+  freshness: { state: 'unknown', observedAt: null, ageMs: null },
+  confidence: { level: 'unknown' },
+};
+
+/**
+ * The empty snapshot for a domain the plugin did not declare.
+ *
+ * Deliberately built per domain rather than one shared `{}`: each snapshot has
+ * required fields, and a caller reading `snapshot.position` must get `null`,
+ * not a TypeError. Domains not listed fall through to `{ quality }`, which is
+ * the one field every snapshot in the design shares.
+ */
+function deniedSnapshot(domain: DeviceBridgeDomain): any {
+  const base = { quality: UNKNOWN_QUALITY };
+  switch (domain) {
+    case 'spatial':
+      return {
+        ...base,
+        position: null,
+        movement: { speedMps: null, bearingDeg: null, distanceRecentM: null, state: 'unknown' },
+        orientation: { headingDeg: null },
+        recentPath: [],
+      };
+    case 'visual':
+      return {
+        ...base,
+        camera: { available: false, active: false, facing: 'unknown' },
+        latest: null,
+        recentTimeline: { windowMs: 0, frames: [] },
+      };
+    case 'deviceContext':
+      return {
+        ...base,
+        power: { batteryLevel: null, charging: null, lowPowerMode: null },
+        thermal: { state: 'unknown' },
+        resources: { memoryPressure: 'unknown', storagePressure: 'unknown' },
+      };
+    case 'connectivity':
+      return {
+        ...base,
+        reachability: 'unknown',
+        transport: 'unknown',
+        qualityClass: 'unknown',
+        stability: 'unknown',
+        latencyMs: null,
+      };
+    case 'interaction':
+      return {
+        ...base,
+        lifecycle: { appState: 'unknown', screenOn: null },
+        audio: { captureActive: null, playbackActive: null, route: 'unknown', interruption: 'unknown' },
+      };
+    case 'activity':
+      return {
+        ...base,
+        // `confidence` is REQUIRED on both blocks in the freeze, precisely
+        // because an inferred activity must never be handed over without
+        // saying how sure the inference is. An empty snapshot is the least
+        // sure of all.
+        human: { state: 'unknown', since: null, confidence: { level: 'unknown' } },
+        devicePose: { placement: 'unknown', orientation: 'unknown', confidence: { level: 'unknown' } },
+        recentTransitions: [],
+      };
+    case 'environment':
+      return {
+        ...base,
+        lighting: { level: 'unknown', lux: null },
+        acoustics: { level: 'unknown', approximateDb: null },
+        // 'unknown' rather than 'uncertain': uncertain means we looked and
+        // could not decide, and nothing looked at all here.
+        enclosure: { state: 'unknown' },
+        proximity: { distanceClass: 'unknown' },
+        nearbySignals: { bleAvailable: false, beaconCount: null, uwbAvailable: false },
+      };
+    case 'capability': {
+      // Every axis unknown — and note this is NOT the same as `denied`.
+      // "I could not check" and "the user said no" lead to different things
+      // being said to the user, which is why the freeze keeps them apart.
+      const unknownStatus = { support: 'unknown', permission: 'unknown', availability: 'unknown' };
+      return {
+        ...base,
+        camera: unknownStatus,
+        microphone: unknownStatus,
+        location: { ...unknownStatus, precision: 'unknown', backgroundPermission: 'unknown' },
+        motion: unknownStatus,
+        bluetooth: unknownStatus,
+        uwb: unknownStatus,
+        nfc: unknownStatus,
+        notifications: unknownStatus,
+        health: unknownStatus,
+        backgroundExecution: unknownStatus,
+      };
+    }
+    default:
+      return base;
+  }
+}
+
+/**
+ * A domain the plugin may not use, or that this build does not implement.
+ *
+ * Reads answer with explicit unknowns. Anything that ACTS — start, stop,
+ * subscribe — throws, because there is no honest "unknown" for an action: a
+ * silent no-op start would leave the caller believing a session is open, and a
+ * subscription that never fires reads as "nothing has changed".
+ */
+function deniedDomain(domain: DeviceBridgeDomain, why: string): any {
+  return {
+    async getSnapshot() { return deniedSnapshot(domain); },
+    async start() { throw denial(domain, why); },
+    async stop() { throw denial(domain, why); },
+    subscribe() { throw denial(domain, why); },
+  };
+}
+
+function denial(domain: DeviceBridgeDomain, why: string): Error {
+  const err: any = new Error(`deviceState.${domain}: ${why}`);
+  // Frozen vocabulary. A manifest gate IS a policy, so a manifest denial is
+  // policyRestricted — no new error vocabulary needed.
+  err.code = 'RESTRICTED';
+  err.domain = domain;
+  return err;
+}
+
+const ALL_DOMAINS: DeviceBridgeDomain[] = [
+  'spatial', 'visual', 'activity', 'deviceContext',
+  'connectivity', 'capability', 'environment', 'interaction',
+];
+
+let _provider: Partial<DeviceState> = {};
+
+/** Host DI: the app supplies the engines it has. Called once at startup. */
+export function setDeviceStateProvider(state: Partial<DeviceState>): void {
+  _provider = state || {};
+}
+
+/**
+ * The `deviceState` a plugin receives, gated by what it declared.
+ *
+ * Every domain is always present — a plugin can call any of the eight without
+ * an existence check. What differs is whether it answers with data, or with
+ * an explicit "I know nothing" and a reason.
+ */
+export function gateDeviceState(declared?: readonly DeviceBridgeDomain[]): DeviceState {
+  const allowed = new Set(declared || []);
+  const out: any = {};
+
+  for (const domain of ALL_DOMAINS) {
+    if (!allowed.has(domain)) {
+      out[domain] = deniedDomain(
+        domain,
+        `not declared in this plugin's stateDomains. Add '${domain}' to use it.`,
+      );
+      continue;
+    }
+    const engine = (_provider as any)[domain];
+    out[domain] = engine ?? deniedDomain(
+      domain,
+      'no engine in this build — the native side does not exist yet. See docs/DEVICE_API_STATUS.md.',
+    );
+  }
+
+  return out as DeviceState;
+}
+
+/**
+ * The `deviceState` a device TOOL call receives: the same domains, but
+ * `subscribe` refuses.
+ *
+ * A declared domain IS the engine, and the engines live as long as the app. A
+ * UI plugin has a mount to unsubscribe in; a tool call has nothing — a listener
+ * `run()` adds outlives it and runs on every later event, once per call that
+ * added one. Refused loudly rather than quietly scoped to the call: a
+ * subscription that stops hearing when `run` returns reads as "nothing has
+ * changed". Everything else passes through untouched.
+ */
+export function withoutSubscribe(state: DeviceState): DeviceState {
+  if (!state) return state;
+  const out: any = {};
+  for (const domain of ALL_DOMAINS) {
+    const d = (state as any)[domain];
+    out[domain] = d && Object.assign(Object.create(d), {
+      subscribe() {
+        throw denial(domain, 'a device tool call has no lifetime to own a subscription. Subscribe from the plugin UI, or read getSnapshot() within the call.');
+      },
+    });
+  }
+  return out as DeviceState;
+}
+
+/** Which domains this build can actually answer — for diagnostics. */
+export function implementedStateDomains(): DeviceBridgeDomain[] {
+  return ALL_DOMAINS.filter(d => !!(_provider as any)[d]);
+}

package/src/hooks/usePlugin.ts

@@ -8,18 +8,23 @@
  *   const { plugin, loading, error } = usePlugin(pluginId, manifest);
  *   if (loading) return <Spinner />;
  *   if (error) return <Error message={error} />;
- *   return <plugin.Component bridge={bridge} native={native} theme={theme} context={context} />;
+ *   return <plugin.Component bridge={bridge} device={device} theme={theme} context={context} />;
  */
 import { useState, useEffect } from 'react';
 import { bundleManager } from '../bundles/bundleManager';
 import { nativePluginRegistry } from '../host';
-import type { RegisteredUIPlugin } from '../sdk/types';
+import { resolvePluginGrants } from '../pluginRuntime';
+import type { NativeCapabilities, RegisteredUIPlugin } from '../sdk/types';
+import type { DeviceBridgeDomain } from '../sdk/device-state';
 
 interface PluginManifestLike {
   version?: string;
   name?: string;
   render?: any;
   _connectorId?: string;
+  capabilities?: Record<string, unknown>;
+  native?: NativeCapabilities;
+  stateDomains?: DeviceBridgeDomain[];
 }
 
 interface UsePluginResult {
@@ -102,6 +107,11 @@ export function usePlugin(pluginId: string, manifest: PluginManifestLike): UsePl
   const bundleHash = extractBundleHash(manifest);
   const componentId = extractComponentId(manifest);
   const lookupId = componentId || pluginId;
+  // The manifest's grants — the authority for the bundle's device tools, the
+  // same one the renderer gates the component with. Keyed by value so a fresh
+  // manifest object with the same grants does not reload the plugin.
+  const grants = resolvePluginGrants({ pluginId, manifest });
+  const grantsKey = JSON.stringify(grants);
 
   if (ignoredUrl) {
     console.warn(`[usePlugin] ${pluginId}: IGNORED connector-injected bundleUrl="${ignoredUrl}". The host derives bundle URLs from pluginId via the canonical route.`);
@@ -132,7 +142,7 @@ export function usePlugin(pluginId: string, manifest: PluginManifestLike): UsePl
         // Path 2: Remote bundle (via global BundleManager)
         if (bundleUrl) {
           try {
-            const component = await bundleManager.load(pluginId, bundleUrl, version, bundleHash);
+            const component = await bundleManager.load(pluginId, bundleUrl, version, bundleHash, grants);
             if (cancelled) return;
             setPlugin(component);
             setLoading(false);
@@ -179,7 +189,7 @@ export function usePlugin(pluginId: string, manifest: PluginManifestLike): UsePl
     })();
 
     return () => { cancelled = true; };
-  }, [pluginId, lookupId, bundleUrl, bundleHash, version]);
+  }, [pluginId, lookupId, bundleUrl, bundleHash, version, grantsKey]);
 
   return { plugin, loading, error, bundleMissing };
 }

package/src/host.ts

@@ -41,19 +41,23 @@ const noopNative: PluginNative = {
   biometrics: unavailable('biometrics'),
   biometricsV2: unavailable('biometricsV2'),
   notifications: unavailable('notifications'),
-  haptics: { impact: () => {}, notification: () => {}, selection: () => {} },
+  haptics: { impact: () => {}, notification: () => {}, selection: () => {}, error: () => {} },
   connectivity: { isOnline: () => true, onChange: () => () => {} },
   fileSystem: unavailable('fileSystem'),
   cookies: unavailable('cookies'),
   sharing: unavailable('sharing'),
   scanner: unavailable('scanner'),
   nfc: unavailable('nfc'),
+  bluetooth: unavailable('bluetooth'),
+  vision: unavailable('vision'),
+  maps: unavailable('maps'),
 };
 
 let _pluginNative: PluginNative = noopNative;
 
 /** Install the device-capabilities implementation plugins receive as
- *  `props.native`. The host owns the native modules. */
+ *  `props.device` (the L1 native modules keep the `native` name; the plugin-
+ *  facing prop is `device`). The host owns the native modules. */
 export function setPluginNativeProvider(native: PluginNative): void {
   _pluginNative = native;
 }
@@ -64,12 +68,12 @@ export function getPluginNative(): PluginNative {
 
 /** Blocked-capability proxy: any call warns and is ignored (no throw) —
  *  matches the reference app's behaviour for undeclared capabilities. */
-function blocked(api: string): any {
+function blocked(api: string, reason?: string): any {
   return new Proxy({}, {
     get: (_t, method) => {
       if (typeof method !== 'string') return undefined;
       return () => {
-        console.warn(`[adas] native.${api}.${method} blocked — capability '${api}' not declared in the plugin manifest`);
+        console.warn(`[adas] native.${api}.${method} blocked — ${reason ?? `capability '${api}' not declared in the plugin manifest`}`);
       };
     },
   });
@@ -87,23 +91,93 @@ function blocked(api: string): any {
 export function gatePluginNative(
   native: PluginNative,
   declared?: NativeCapabilities,
+  pluginId?: string,
 ): PluginNative {
   const caps = declared || {};
-  return {
+  // Per-plugin filesystem + storage isolation, FAIL CLOSED. A declared plugin
+  // gets a sandbox/namespace scoped to its OWN id (plugin-files/<pluginId>/,
+  // @plugin:<id>: KV, plugin-storage-<id>.db) via the provider's
+  // fileSystemFor/storageFor. There is deliberately NO shared fallback: if the
+  // id is missing or the provider can't scope, the plugin is BLOCKED, not handed
+  // a bucket some other plugin also holds. A silent shared fallback is exactly
+  // the P1 that reopened when the UI renderer omitted the id — the isolation must
+  // fail closed, never degrade to "shared" without anyone noticing.
+  const scopedFileSystem =
+    native.fileSystemFor && pluginId ? native.fileSystemFor(pluginId) : null;
+  const scopedStorage =
+    native.storageFor && pluginId ? native.storageFor(pluginId) : null;
+  const gated = {
     camera: caps.camera ? native.camera : blocked('camera'),
     location: caps.location ? native.location : blocked('location'),
-    storage: caps.offline ? native.storage : blocked('storage'),
+    storage: caps.offline
+      ? (scopedStorage ?? blocked('storage', "no trusted pluginId to scope storage — refusing shared access (fail closed)"))
+      : blocked('storage'),
     biometrics: caps.biometrics ? native.biometrics : blocked('biometrics'),
     biometricsV2: caps.biometricsV2 ? native.biometricsV2 : blocked('biometricsV2'),
     notifications: caps.notifications ? native.notifications : blocked('notifications'),
     haptics: caps.haptics ? native.haptics : blocked('haptics'),
     connectivity: native.connectivity,
-    fileSystem: caps.fileSystem ? native.fileSystem : blocked('fileSystem'),
+    fileSystem: caps.fileSystem
+      ? (scopedFileSystem ?? blocked('fileSystem', "no trusted pluginId to scope the filesystem — refusing shared access (fail closed)"))
+      : blocked('fileSystem'),
     cookies: caps.cookies ? native.cookies : blocked('cookies'),
     sharing: caps.sharing ? native.sharing : blocked('sharing'),
     scanner: caps.scanner ? native.scanner : blocked('scanner'),
     nfc: caps.nfc ? native.nfc : blocked('nfc'),
-  };
+    // Gated like the rest even though nothing implements it yet. An undeclared
+    // plugin gets the usual blocked proxy; a DECLARED one reaches an API whose
+    // every method refuses by name. Both are better than the `undefined` this
+    // used to be, which crashed with "cannot read properties of undefined".
+    bluetooth: caps.bluetooth ? native.bluetooth : blocked('bluetooth'),
+    vision: caps.vision ? native.vision : blocked('vision'),
+    maps: caps.maps ? native.maps : blocked('maps'),
+    // What this plugin DECLARED, carried on the object it already receives.
+    //
+    // It is how a COMPONENT can be capability-gated: <CameraPreview> is handed
+    // `native` and reads this, so showing the camera obeys the same flag as
+    // calling it. Without this the preview would be a second door to the camera
+    // with only one lock. Non-enumerable so it cannot be mistaken for an API.
+  } as any;
+
+  Object.defineProperty(gated, '__declaredCapabilities', {
+    value: Object.freeze({ ...caps }),
+    enumerable: false,
+    writable: false,
+  });
+  return gated;
+}
+
+// ── Camera preview (the plugin-facing way to SHOW the camera) ─────────────
+//
+// A plugin composes <CameraPreview native={native} /> from the SDK; the HOST
+// supplies what actually renders, because only the host has the native module.
+//
+// This exists so we do NOT register raw `expo-camera` for bundles. That would
+// be a third door to the device with no capability gate and no honest failure
+// mode — a plugin could mount a camera without declaring it. Here the pixels
+// stay on the host's side: a plugin can SHOW the camera and still cannot touch
+// a frame.
+
+/** Props the host's preview implementation receives. */
+export interface CameraPreviewImplProps {
+  facing?: 'front' | 'back';
+  style?: any;
+  renderUnavailable?: (reason: string) => any;
+}
+
+let _cameraPreview: ((props: CameraPreviewImplProps) => any) | null = null;
+
+/** Install the host's camera preview (e.g. an expo-camera CameraView). */
+export function setCameraPreviewProvider(
+  Component: ((props: CameraPreviewImplProps) => any) | null,
+): void {
+  _cameraPreview = Component;
+}
+
+/** Null when the host installed none — the SDK then renders a stated reason,
+ *  never a black rectangle that looks like a dark room. */
+export function getCameraPreviewProvider(): ((props: CameraPreviewImplProps) => any) | null {
+  return _cameraPreview;
 }
 
 // ── Native (host-bundled) plugin registry ─────────────────────────────────

package/src/index.ts

@@ -13,14 +13,76 @@
  * No Expo imports — @ateam-ai-mobile/expo supplies the Expo-backed providers.
  */
 
-// Plugin SDK (plugin-author surface)
+// Plugin SDK (plugin-author surface) — the MECHANICAL layer.
+// `props.device.*`: verbs, bare values, throws when it cannot.
 export * from './sdk';
 
+// Device Bridge v2 — the SEMANTIC layer. `props.deviceState.*`: state names,
+// snapshots carrying freshness and confidence, and reads that say `unknown`
+// rather than throwing.
+//
+// Exported under its own path rather than star-exported into this namespace,
+// deliberately: the whole point of the layer is that a reader can tell at a
+// glance which one they are in, and merging both into one import undoes that.
+export * as deviceStateV2 from './sdk/device-state';
+export type {
+  DeviceState,
+  DeviceBridgeDomain,
+  StateQuality,
+  Freshness,
+  Confidence,
+  VisualSnapshot,
+  SpatialSnapshot,
+  SpatialPoint,
+  SpatialIntent,
+  SpatialEvent,
+  SpatialStateEvent,
+  StateEvent,
+  StateListener,
+  Subscription,
+  ActivitySnapshot,
+  EnvironmentSnapshot,
+  InteractionSnapshot,
+  CapabilitySnapshot,
+  CapabilityStatus,
+  DeviceContextSnapshot,
+  ConnectivitySnapshot,
+} from './sdk/device-state';
+// Device Bridge v2 runtime helpers (VALUES). `neverObserved` is the canonical
+// `unknown` freshness the engine's quality module derives from; the others were
+// already in the built types but missing from the source root export.
+export {
+  neverObserved,
+  isActionable,
+  explainCapability,
+} from './sdk/device-state';
+
+// Device Bridge v2 host DI — the semantic counterpart of
+// setPluginNativeProvider. Separate module on purpose: the moment the two
+// layers share one, the boundary starts to blur.
+export {
+  setDeviceStateProvider,
+  gateDeviceState,
+  implementedStateDomains,
+} from './deviceStateHost';
+
+// Voice session host DI — the app hands its one live session here, and the gate
+// (called only via resolvePluginRuntimeProps) decides per-plugin exposure. Its
+// own file for the same reason deviceState is: a session is neither a mechanical
+// verb nor a device domain, and merging it in would blur that.
+export {
+  setVoiceProvider,
+  gateVoice,
+  implementedVoice,
+} from './voiceHost';
+
 // Host integration
 export {
   setHapticsProvider,
   getHaptics,
   setPluginNativeProvider,
+  setCameraPreviewProvider,
+  getCameraPreviewProvider,
   getPluginNative,
   gatePluginNative,
   registerNativePlugin,
@@ -29,10 +91,42 @@ export {
   registerBundleModules,
 } from './host';
 
+// The ONE runtime contract that gates a plugin's device surface (device/native +
+// deviceState) — every renderer AND its device tools resolve grants through it,
+// so a plugin gets identical access on every surface and in its tools.
+export { resolvePluginRuntimeProps, resolvePluginGrants } from './pluginRuntime';
+export type { PluginRuntimeProps, PluginRuntimeSource, PluginGrants } from './pluginRuntime';
+
+// Device tools (plugin `tools/` sections — registered at bundle load)
+export {
+  registerDeviceTools,
+  unregisterDeviceTools,
+  setDeviceToolContextProvider,
+  callDeviceTool,
+  listDeviceTools,
+  hasDeviceTool,
+  clearDeviceTools,
+} from './tools/registry';
+export type { DeviceToolSummary, DeviceToolOutcome } from './tools/registry';
+export { ensureDeviceToolsLoaded, resetDeviceToolLoader } from './tools/loader';
+export { registerPlatformDeviceTools } from './tools/platformTools';
+export {
+  syncDeviceToolsForSession,
+  deviceToolsActionForSession,
+  __resetSessionSyncForTest,
+} from './tools/sessionSync';
+export type { SessionSnapshot, DeviceToolsAction, DeviceToolsSessionDeps } from './tools/sessionSync';
+export {
+  handleServerDeviceToolCall,
+  isDeviceToolCommand,
+  setDeviceToolResultPoster,
+} from './tools/serverCalls';
+
 // Bundles
 export { bundleManager } from './bundles/bundleManager';
+export type { LoadedBundleInfo, LoadedBundleSource } from './bundles/bundleManager';
 export { setBundleStorage, MemoryBundleStorage } from './bundles/storage';
-export type { BundleStorage, BundleCacheEntry } from './bundles/storage';
+export type { BundleStorage, BundleCacheEntry, TrustedToolDeclaration } from './bundles/storage';
 
 // Bridge
 export { useNativeBridge, createNativeBridge } from './bridge/native';