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

package/src/bundles/bundleManager.ts

@@ -6,7 +6,7 @@
  * the BundleStorage adapter (in-memory by default; @ateam-ai-mobile/expo provides disk).
  *
  * Usage:
- *   const component = await bundleManager.load(pluginId, bundleUrl, version, hash);
+ *   const component = await bundleManager.load(pluginId, bundleUrl, version, hash, grants);
  *   // component = { id, type, Component, ... } (RegisteredUIPlugin)
  */
 import React from 'react';
@@ -25,8 +25,9 @@ import SurfaceDispatcher from '../registry/SurfaceDispatcher';
 import { resolveBundleModule } from '../host';
 import { sha256Hex } from '../utils/sha256';
 import { assertBundleIntegrity } from './integrity';
-import { getBundleStorage, type BundleCacheEntry } from './storage';
+import { getBundleStorage, type BundleCacheEntry, type TrustedToolDeclaration } from './storage';
 import { registerDeviceTools, unregisterDeviceTools, listDeviceTools } from '../tools/registry';
+import type { PluginGrants } from '../pluginRuntime';
 import type { RegisteredUIPlugin } from '../sdk/types';
 
 // ── Require shim ─────────────────────────────────────────────
@@ -90,6 +91,12 @@ const requireShim = (name: string) => {
 
 const CACHE_TTL = 7 * 24 * 60 * 60 * 1000; // 7 days
 
+// What findPluginExport looks for: a renderable plugin, or one with a `tools` section.
+const hasComponent = (val: any): boolean =>
+  !!val && typeof val === 'object' && typeof val.Component === 'function';
+const hasTools = (val: any): boolean =>
+  !!val && typeof val === 'object' && Array.isArray(val.tools) && val.tools.length > 0;
+
 // ── BundleManager singleton ──────────────────────────────────
 
 /** Where the bytes currently running came from. */
@@ -148,6 +155,10 @@ class BundleManager {
    */
   private registeredToolPluginIds = new Set<string>();
 
+  /** bundleUrl → the trusted declaration last recorded on its disk-cache entry
+   *  this session, so a memory hit with unchanged grants skips the index I/O. */
+  private recordedDeclarations = new Map<string, string>();
+
   /**
    * Enforce the in-memory tenant boundary. Call at the top of every public load
    * path, BEFORE any cache read.
@@ -193,6 +204,7 @@ class BundleManager {
       try { unregisterDeviceTools(pluginId); } catch { /* ignore */ }
     }
     this.registeredToolPluginIds.clear();
+    this.recordedDeclarations.clear();
     this.modules.clear();
     this.provenance.clear();
     this.inflight.clear();
@@ -208,13 +220,15 @@ class BundleManager {
     return this.epoch !== epoch || getTenant() !== tenant;
   }
 
-  /** Flip an existing provenance record to source:'memory' — a later serve of an
-   *  already-evaluated bundle came from the in-memory cache, not a fresh
-   *  download/disk read. No-op if nothing was recorded yet. */
-  private markMemoryHit(bundleUrl: string): void {
+  /** Record a memory serve: the running bytes are the already-evaluated module,
+   *  and `expected` is refreshed from the manifest hash the caller JUST passed —
+   *  so after a redeploy the record reads hash !== expected (STALE) instead of
+   *  the old in-sync pair. The ONE place both memory paths (load()'s early return
+   *  and loadModule's) record reuse. No-op if nothing was recorded yet. */
+  private markMemoryHit(bundleUrl: string, expectedHash?: string): void {
     const prev = this.provenance.get(bundleUrl);
-    if (prev && prev.source !== 'memory') {
-      this.provenance.set(bundleUrl, { ...prev, source: 'memory' });
+    if (prev) {
+      this.provenance.set(bundleUrl, { ...prev, source: 'memory', expected: expectedHash?.toLowerCase() ?? prev.expected });
     }
   }
 
@@ -228,12 +242,20 @@ class BundleManager {
    * provided for any bundle the user has not previously verified — without
    * it, a tampered bundle is `eval`'d as JS with full RN runtime + every
    * native capability the manifest declares.
+   *
+   * `grants` is what the MANIFEST grants this plugin (resolvePluginGrants) — the
+   * only authority its device tools are registered under. Omitted (e.g. a
+   * prewarm from the slim plugin list) → the bundle is loaded but its tools are
+   * NOT registered: without the manifest there is nothing trusted to gate them
+   * on, and registering with nothing would downgrade a registration the
+   * manifest-driven tool loader already made.
    */
   async load(
     pluginId: string,
     bundleUrl: string,
     version: string,
     expectedHash?: string,
+    grants?: PluginGrants,
   ): Promise<RegisteredUIPlugin> {
     // Tenant boundary FIRST — fail closed without a tenant, drop the previous
     // tenant's modules on a switch, and CAPTURE the tenant + generation at entry
@@ -248,7 +270,8 @@ class BundleManager {
       // this the provenance would freeze on the first download/disk source and
       // getLoadedBundles() would never report a memory serve. (loadModule's
       // own memory branch covers the loadTools path, which has no early return.)
-      this.markMemoryHit(bundleUrl);
+      this.markMemoryHit(bundleUrl, expectedHash);
+      if (grants) await this.commitTools(pluginId, bundleUrl, grants, tenant, epoch);
       return cached;
     }
 
@@ -277,6 +300,10 @@ class BundleManager {
       throw new Error('[BundleManager] tenant changed while loading — discarding (fail closed)');
     }
 
+    // Tools register at LOAD, not at mount — and for a UI bundle too, so a hybrid
+    // plugin's tools are callable whether or not its component is found.
+    if (grants) await this.commitTools(pluginId, bundleUrl, grants, tenant, epoch);
+
     // 3. Extract component for this specific pluginId
     const component = this.getComponentFromMemory(pluginId, bundleUrl);
     if (!component) {
@@ -295,13 +322,20 @@ class BundleManager {
    * Same download, same integrity check, same evaluation as `load()`; the only
    * difference is that a bundle exporting tools and no `Component` is a success
    * here rather than "no component found". Returns the tool names registered.
+   *
+   * `grants` is REQUIRED: the tools are registered under `pluginId` with exactly
+   * what the manifest grants (see load()), never what the bundle claims.
    */
   async loadTools(
     pluginId: string,
     bundleUrl: string,
     version: string,
-    expectedHash?: string,
+    expectedHash: string | undefined,
+    grants: PluginGrants,
   ): Promise<string[]> {
+    if (!grants) {
+      throw new Error(`[BundleManager] loadTools(${pluginId}) needs the manifest's grants (resolvePluginGrants) — refusing to register tools on the bundle's own claim`);
+    }
     // Tenant boundary FIRST — same fail-closed / drop-on-switch as load(), and
     // capture the tenant + generation for the stale check after the async load.
     const tenant = this.requireTenant();
@@ -322,6 +356,7 @@ class BundleManager {
     if (this.isStale(epoch, tenant)) {
       throw new Error('[BundleManager] tenant changed while loading tools — discarding (fail closed)');
     }
+    await this.commitTools(pluginId, bundleUrl, grants, tenant, epoch);
 
     const names = listDeviceTools()
       .filter(t => t.pluginId === pluginId)
@@ -347,6 +382,8 @@ class BundleManager {
     bundleUrl: string;
     version: string;
     bundleHash?: string;
+    /** The manifest's grants, when the caller has the manifest (see load()). */
+    grants?: PluginGrants;
   }>): Promise<void> {
     const queue = [...items];
     const concurrency = Math.min(3, queue.length);
@@ -359,7 +396,7 @@ class BundleManager {
         const it = queue.shift();
         if (!it) return;
         try {
-          await this.load(it.pluginId, it.bundleUrl, it.version, it.bundleHash);
+          await this.load(it.pluginId, it.bundleUrl, it.version, it.bundleHash, it.grants);
           okCount++;
         } catch (err) {
           failCount++;
@@ -438,8 +475,7 @@ class BundleManager {
     // Already in memory? Then the running bytes are whatever this session
     // already evaluated — record the reuse so provenance never goes silent.
     if (this.modules.has(bundleUrl)) {
-      const prev = this.provenance.get(bundleUrl);
-      if (prev) this.provenance.set(bundleUrl, { ...prev, source: 'memory', expected: expectedHash?.toLowerCase() ?? prev.expected });
+      this.markMemoryHit(bundleUrl, expectedHash);
       return;
     }
 
@@ -551,37 +587,112 @@ class BundleManager {
       `[BundleManager] RUNNING ${bundleUrl} v${version} sha=${(verifiedHash || 'none').slice(0, 12)} ` +
       `(${servedFrom}${expectedLc && verifiedHash && expectedLc !== verifiedHash ? `, EXPECTED ${expectedLc.slice(0, 12)} — STALE` : ''})`,
     );
+  }
 
-    // Tools register at LOAD, not at mount — that is what makes a tool callable
-    // with nothing of the plugin on screen.
-    this.registerToolsFromModule(mod, bundleUrl);
+  /**
+   * Register THIS plugin's device tools under the TRUSTED declaration, then
+   * record that declaration on the disk-cache entry. Runs on every trusted load
+   * — memory hit included — so the grants in force are always the latest the
+   * manifest gave (a revoked grant stops applying on the next load, not the next
+   * app start). Callers run it only after their stale check.
+   */
+  private async commitTools(
+    pluginId: string,
+    bundleUrl: string,
+    grants: PluginGrants,
+    tenant: string,
+    epoch: number,
+  ): Promise<void> {
+    const declaration: TrustedToolDeclaration = {
+      pluginId,
+      capabilities: grants.capabilities,
+      stateDomains: grants.stateDomains,
+    };
+    this.registerToolsFromModule(this.modules.get(bundleUrl), declaration);
+    await this.recordTrustedDeclaration(bundleUrl, declaration, tenant, epoch);
   }
 
   /**
-   * Pick up every `tools` section in an evaluated bundle and put it in the
-   * device tool registry. Runs for UI, hybrid and tools-only bundles alike: a
-   * plugin that ships both gets its tools registered without its UI mounting.
+   * Put the plugin's own `tools` section in the device tool registry — under the
+   * pluginId and grants the MANIFEST resolved, never the bundle's own `id`,
+   * `capabilities` or `stateDomains`. A bundle is code the manifest authorised
+   * by hash; what it may touch is the manifest's to say, same as its rendered
+   * surface (resolvePluginRuntimeProps). Its own `id` would also let it register
+   * as another plugin — including the host's platform tools, which a same-id
+   * re-registration replaces.
+   *
+   * Only this plugin's export (the same lookup the component uses) is
+   * registered. Another export's tools in the same bundle belong to another
+   * plugin and register when THAT plugin's manifest loads it.
    */
-  private registerToolsFromModule(mod: any, bundleUrl: string): void {
+  private registerToolsFromModule(mod: any, { pluginId, capabilities, stateDomains }: TrustedToolDeclaration): void {
     if (!mod) return;
 
-    for (const key of Object.keys(mod)) {
-      const val = mod[key];
-      if (!val || typeof val !== 'object' || !Array.isArray(val.tools) || val.tools.length === 0) {
-        continue;
-      }
-      const pluginId = typeof val.id === 'string' ? val.id : `${bundleUrl}#${key}`;
-      try {
-        registerDeviceTools(pluginId, val.tools, val.capabilities, val.stateDomains);
-        // Remember it so a tenant switch (or clearAll) can unregister the OLD
-        // tenant's tools before the incoming tenant re-registers.
-        this.registeredToolPluginIds.add(pluginId);
-      } catch (err) {
-        console.warn(
-          `[BundleManager] tool registration failed for ${pluginId}:`,
-          err instanceof Error ? err.message : String(err),
-        );
+    const own = this.findPluginExport(mod, pluginId, hasTools);
+    const others = Object.keys(mod).filter((k) => hasTools(mod[k]) && mod[k] !== own);
+    if (others.length > 0) {
+      console.warn(
+        `[BundleManager] ${pluginId}: not registering tools from export(s) ${others.join(', ')} — ` +
+        `they are not this plugin's, and only their own manifest can grant them`,
+      );
+    }
+    if (!own) return;
+
+    // The bundle's own declaration grants nothing, but a gap between it and the
+    // manifest is the author's bug — name it, or the tool just reads "not declared".
+    const ungranted = [
+      ...(Array.isArray(own.stateDomains) ? own.stateDomains : []).filter((d: any) => !stateDomains?.includes(d)),
+      ...Object.keys(own.capabilities || {}).filter((k) => own.capabilities[k] === true && !(capabilities as any)?.[k]),
+    ];
+    if (ungranted.length > 0) {
+      console.warn(
+        `[BundleManager] ${pluginId}: bundle declares ${ungranted.join(', ')} but the manifest does not grant it — denied`,
+      );
+    }
+
+    try {
+      registerDeviceTools(pluginId, own.tools, capabilities, stateDomains);
+      // Remember it so a tenant switch (or clearAll) can unregister the OLD
+      // tenant's tools before the incoming tenant re-registers.
+      this.registeredToolPluginIds.add(pluginId);
+    } catch (err) {
+      console.warn(
+        `[BundleManager] tool registration failed for ${pluginId}:`,
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }
+
+  /**
+   * Record the trusted declaration on this tenant's disk-cache entry for the
+   * bytes RUNNING — the recovery path (tools/loader loadFromDiskCache) has no
+   * manifest and re-registers with exactly this. Only onto an entry this tenant
+   * owns whose hash is the running hash: the grant was issued for these bytes,
+   * and those are the bytes recovery will evaluate. Best-effort — a lost write
+   * leaves no `trusted`, which recovery treats as fail closed.
+   */
+  private async recordTrustedDeclaration(
+    bundleUrl: string,
+    declaration: TrustedToolDeclaration,
+    tenant: string,
+    epoch: number,
+  ): Promise<void> {
+    const key = JSON.stringify(declaration);
+    if (this.recordedDeclarations.get(bundleUrl) === key) return;
+    try {
+      const storage = getBundleStorage();
+      const index = await storage.loadIndex();
+      const entry = index[bundleUrl];
+      const running = this.provenance.get(bundleUrl)?.hash;
+      if (!entry || entry.tenant !== tenant || !running || entry.bundleHash?.toLowerCase() !== running) return;
+      if (this.isStale(epoch, tenant)) return;
+      if (JSON.stringify(entry.trusted) !== key) {
+        index[bundleUrl] = { ...entry, trusted: declaration };
+        await storage.saveIndex(index);
       }
+      this.recordedDeclarations.set(bundleUrl, key);
+    } catch (err) {
+      console.warn('[BundleManager] could not record trusted declaration:', err);
     }
   }
 
@@ -691,44 +802,37 @@ class BundleManager {
 
   // ── Private: component extraction ───────────────────────────
 
+  /** Find a plugin component in a loaded module. */
+  private getComponentFromMemory(pluginId: string, bundleUrl: string): RegisteredUIPlugin | null {
+    return this.findPluginExport(this.modules.get(bundleUrl), pluginId, hasComponent);
+  }
+
   /**
-   * Find a plugin component in a loaded module.
-   * Handles: default export, direct key match, multi-plugin .id match.
+   * Find THIS plugin's export in a loaded module — the one lookup both the
+   * component and the device tools use, so a plugin's UI and its tools always
+   * come from the same export. `accept` says what the caller needs from it.
+   * Handles: direct key match, PascalCase key, default export, multi-plugin .id match.
    */
-  private getComponentFromMemory(pluginId: string, bundleUrl: string): RegisteredUIPlugin | null {
-    const mod = this.modules.get(bundleUrl);
+  private findPluginExport(mod: any, pluginId: string, accept: (val: any) => boolean): any | null {
     if (!mod) return null;
 
     const shortName = pluginId.includes(':') ? pluginId.split(':').pop()! : pluginId;
 
     // 1. Direct key match (full pluginId as key)
-    if (mod[pluginId] && typeof mod[pluginId].Component === 'function') {
-      return mod[pluginId] as RegisteredUIPlugin;
-    }
+    if (accept(mod[pluginId])) return mod[pluginId];
 
     // 2. PascalCase match from shortName (most reliable for combined bundles)
     //    e.g., "memories-panel" → "MemoriesPanel"
     const pascal = shortName.replace(/(^|-)([a-z])/g, (_: string, __: string, c: string) => c.toUpperCase());
-    if (mod[pascal] && typeof mod[pascal] === 'object' && typeof mod[pascal].Component === 'function') {
-      return mod[pascal] as RegisteredUIPlugin;
-    }
+    if (accept(mod[pascal])) return mod[pascal];
 
     // 3. Default export (single-plugin bundles)
-    if (mod.default && typeof mod.default === 'object' && typeof mod.default.Component === 'function') {
-      return mod.default as RegisteredUIPlugin;
-    }
+    if (accept(mod.default)) return mod.default;
 
     // 4. Match by .id field (last resort — can be unreliable in combined bundles)
     for (const key of Object.keys(mod)) {
       const val = mod[key];
-      if (
-        val &&
-        typeof val === 'object' &&
-        val.id === shortName &&
-        typeof val.Component === 'function'
-      ) {
-        return val as RegisteredUIPlugin;
-      }
+      if (val && (val.id === pluginId || val.id === shortName) && accept(val)) return val;
     }
 
     return null;

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;
@@ -27,6 +28,24 @@ export interface BundleCacheEntry {
    * 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;
 }
 
 /**

package/src/deviceStateHost.ts

@@ -191,6 +191,31 @@ export function gateDeviceState(declared?: readonly DeviceBridgeDomain[]): Devic
   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

@@ -13,13 +13,18 @@
 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

@@ -50,6 +50,7 @@ const noopNative: PluginNative = {
   nfc: unavailable('nfc'),
   bluetooth: unavailable('bluetooth'),
   vision: unavailable('vision'),
+  maps: unavailable('maps'),
 };
 
 let _pluginNative: PluginNative = noopNative;
@@ -129,6 +130,7 @@ export function gatePluginNative(
     // 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

package/src/index.ts

@@ -35,6 +35,11 @@ export type {
   SpatialSnapshot,
   SpatialPoint,
   SpatialIntent,
+  SpatialEvent,
+  SpatialStateEvent,
+  StateEvent,
+  StateListener,
+  Subscription,
   ActivitySnapshot,
   EnvironmentSnapshot,
   InteractionSnapshot,
@@ -86,11 +91,11 @@ export {
   registerBundleModules,
 } from './host';
 
-// The ONE runtime contract every renderer uses to gate a plugin's device surface
-// (device/native + deviceState) — so a plugin gets identical access on every
-// surface. See pluginRuntime.ts for why this is centralized.
-export { resolvePluginRuntimeProps } from './pluginRuntime';
-export type { PluginRuntimeProps, PluginRuntimeSource } from './pluginRuntime';
+// 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 {
@@ -121,7 +126,7 @@ export {
 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';

package/src/pluginRuntime.ts

@@ -1,7 +1,7 @@
 /**
  * The ONE runtime contract that turns a plugin's declarations into its gated
  * device surface — `props.device` / `props.native` (L2) and `props.deviceState`
- * (L3) — for EVERY renderer, on EVERY surface.
+ * (L3) — for EVERY renderer, on EVERY surface, and for its device tools.
  *
  * WHY THIS EXISTS. Each renderer used to resolve this itself: the embedded route
  * gated both `native` and `deviceState`; the drawer/fullscreen renderer gated
@@ -29,11 +29,6 @@ export interface PluginRuntimeProps {
   voice: VoiceAPI;
 }
 
-/**
- * Where a plugin's declarations come from. TRUSTED source resolution lives here,
- * not in each caller: the server `manifest` wins, the loaded bundle's own default
- * export is the fallback.
- */
 /** One declaration source — either the server manifest or the registry entry. */
 interface PluginDeclaration {
   capabilities?: NativeCapabilities | Record<string, unknown>;
@@ -68,9 +63,18 @@ function mergeCaps(decl: PluginDeclaration | null | undefined): NativeCapabiliti
   return { ...(decl.native as any), ...(decl.capabilities as any) } as NativeCapabilities;
 }
 
+/** What a plugin is GRANTED — resolved from its one trusted source. The same
+ *  value gates its rendered surface and its device tools (the tool registry
+ *  receives it through bundleManager.load/loadTools). */
+export interface PluginGrants {
+  capabilities?: NativeCapabilities;
+  stateDomains?: DeviceBridgeDomain[];
+}
+
 /**
- * Turn a plugin's declarations into the gated { device, native, deviceState } it
- * receives — the SINGLE place this happens, so every surface is identical.
+ * Resolve a plugin's grants — the SINGLE place this happens, for every rendered
+ * surface AND for the device tools its bundle registers, so a plugin gets
+ * identical access through either.
  *
  * TRUST BOUNDARY. Exactly ONE source is authoritative: the server `manifest` for
  * a remote plugin, the registry `plugin` for a host-owned one. They are NEVER
@@ -80,10 +84,17 @@ function mergeCaps(decl: PluginDeclaration | null | undefined): NativeCapabiliti
  * not carry `stateDomains` for a remote plugin, the fix is Core passing it, not
  * trusting the bundle: Core already holds the solution's declaration.)
  */
-export function resolvePluginRuntimeProps(src: PluginRuntimeSource): PluginRuntimeProps {
+export function resolvePluginGrants(src: PluginRuntimeSource): PluginGrants {
   const trusted = src.manifest ?? src.plugin ?? null;
-  const capabilities = mergeCaps(trusted);
-  const stateDomains = trusted?.stateDomains;
+  // Copied, so the grant cannot change after the fact by mutating the source.
+  const stateDomains = trusted?.stateDomains ? [...trusted.stateDomains] : undefined;
+  return { capabilities: mergeCaps(trusted), stateDomains };
+}
+
+/** Turn a plugin's grants into the gated { device, native, deviceState, voice } it
+ *  receives on every rendered surface. */
+export function resolvePluginRuntimeProps(src: PluginRuntimeSource): PluginRuntimeProps {
+  const { capabilities, stateDomains } = resolvePluginGrants(src);
   const native = gatePluginNative(getPluginNative(), capabilities, src.pluginId);
   const deviceState = gateDeviceState(stateDomains);
   // Voice is a capability flag, gated the same way — the TRUSTED declaration