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

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';
@@ -23,10 +23,21 @@ import SurfaceFullscreen from '../surfaces/SurfaceFullscreen';
 import { useSurfaceStore } from '../registry/store';
 import SurfaceDispatcher from '../registry/SurfaceDispatcher';
 import { resolveBundleModule } from '../host';
+import { PLUGIN_SDK_MODULE, sdkModuleRefusal } from './bundleModuleNames';
 import { sha256Hex } from '../utils/sha256';
 import { assertBundleIntegrity } from './integrity';
-import { getBundleStorage, type BundleCacheEntry } from './storage';
+import { getBundleStorage, loadCacheIndex, type BundleCacheEntry, type TrustedToolDeclaration } from './storage';
+import { pluginBundleUrl, isPluginBundleUrl } from './bundleUrl';
+
+/** The key a plugin's bundle is held under: its ONE canonical URL whenever the
+ *  URL given is that plugin's route in any spelling (MGAP-C8). Any other URL is
+ *  used as given. Every public load enters through this, so no caller, whichever
+ *  spelling it holds, can make one plugin load twice. */
+function bundleKey(pluginId: string, bundleUrl: string): string {
+  return isPluginBundleUrl(bundleUrl, pluginId) ? pluginBundleUrl(pluginId) : bundleUrl;
+}
 import { registerDeviceTools, unregisterDeviceTools, listDeviceTools } from '../tools/registry';
+import type { PluginGrants } from '../pluginRuntime';
 import type { RegisteredUIPlugin } from '../sdk/types';
 
 // ── Require shim ─────────────────────────────────────────────
@@ -34,7 +45,9 @@ import type { RegisteredUIPlugin } from '../sdk/types';
 // so they emit require() calls that this shim resolves at runtime. Anything
 // beyond the built-ins (react-native-webview, expo-linking, …) must be
 // registered by the host via registerBundleModules() — the host is the one
-// that actually has those modules installed.
+// that actually has those modules installed. Any other name in the SDK's own
+// namespaces ('@ateam-ai-mobile/*', '@adas/*') fails the evaluation BY NAME —
+// see bundleModuleNames.ts for why that, and only that, is not warn-and-{}.
 
 const ReactShim: any = {
   __esModule: true,
@@ -79,7 +92,9 @@ const PluginSDKShim = Object.freeze({
 const requireShim = (name: string) => {
   if (name === 'react') return ReactShim;
   if (name === 'react-native') return ReactNative;
-  if (name === '@adas/plugin-sdk') return PluginSDKShim;
+  if (name === PLUGIN_SDK_MODULE) return PluginSDKShim;
+  const refusal = sdkModuleRefusal(name);
+  if (refusal) throw new Error(`[BundleManager] ${refusal}`);
   const hostModule = resolveBundleModule(name);
   if (hostModule !== undefined) return hostModule;
   console.warn(`[BundleManager] Unknown module: ${name} — register it via registerBundleModules()`);
@@ -90,6 +105,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 +169,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 +218,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 +234,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,13 +256,22 @@ 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> {
+    bundleUrl = bundleKey(pluginId, bundleUrl);
     // Tenant boundary FIRST — fail closed without a tenant, drop the previous
     // tenant's modules on a switch, and CAPTURE the tenant + generation at entry
     // so a switch during the async load is caught before any result is used.
@@ -248,7 +285,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 +315,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 +337,21 @@ 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`);
+    }
+    bundleUrl = bundleKey(pluginId, bundleUrl);
     // 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 +372,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 +398,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 +412,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++;
@@ -393,11 +446,14 @@ class BundleManager {
    */
   async clearPlugin(pluginId: string): Promise<void> {
     const storage = getBundleStorage();
-    const index = await storage.loadIndex();
-    const entry = index[pluginId];
+    const index = await loadCacheIndex(storage);
+    // The index is keyed by bundle URL (0ea266d4), so the plugin's entry is
+    // under its canonical URL, never under its id.
+    const bundleUrl = pluginBundleUrl(pluginId);
+    const entry = index[bundleUrl];
     if (entry) {
-      this.modules.delete(entry.bundleUrl);
-      delete index[pluginId];
+      this.modules.delete(bundleUrl);
+      delete index[bundleUrl];
       await storage.saveIndex(index);
       try {
         await storage.deleteBundle(entry.localPath);
@@ -438,13 +494,12 @@ 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;
     }
 
     const storage = getBundleStorage();
-    const index = await storage.loadIndex();
+    const index = await loadCacheIndex(storage);
     const expectedLc = expectedHash ? expectedHash.toLowerCase() : null;
 
     // Check disk cache. A cache hit is only valid when the cached SHA-256
@@ -551,37 +606,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 loadCacheIndex(storage);
+      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 +821,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/bundleModuleNames.ts

@@ -0,0 +1,52 @@
+/**
+ * The SDK's module names, as a remote bundle sees them.
+ *
+ * A bundle keeps its SDK external, and the require shim (bundleManager) answers
+ * exactly ONE SDK name: '@adas/plugin-sdk'. The same code is published to npm as
+ * '@ateam-ai-mobile/plugin-runtime' — but that is the HOST app's dependency, and
+ * inside a bundle it resolves to nothing.
+ *
+ * Until MGAP-C2 (2026-09-27) the shim answered that name the way it answers any
+ * unknown module: a console warning and `{}`. So a bundle doing
+ * `import { CameraPreview } from '@ateam-ai-mobile/plugin-runtime'` evaluated
+ * cleanly, got `undefined`, and crashed on first render as "undefined is not a
+ * component" — nowhere near the import that caused it. The app's in-app
+ * reference HUD imports it that way (it is host code, compiled with the app, so
+ * the name resolves there), and that is where an agent copied it from.
+ *
+ * So the SDK's own namespaces fail BY NAME at evaluation:
+ *   - '@ateam-ai-mobile/*' — the host's packages, never a bundle's.
+ *   - '@adas/*' other than '@adas/plugin-sdk' — the SDK's own docs once told
+ *     plugin authors to import '@adas/device-state' (sdk/device-state.ts header,
+ *     4110943), a name the shim never resolved. There is one SDK module name.
+ * Neither is aliased to '@adas/plugin-sdk': two names for one SDK is a second
+ * source of truth, and that is what this closes (CORE's call). The shim checks
+ * them BEFORE the host's module registry, so no host registration can alias one
+ * either.
+ *
+ * Every OTHER unknown module keeps the warning and `{}`. What exists there is
+ * the host's decision, not the SDK's — each host registers its own set
+ * (@ateam-ai-mobile/expo adds expo-web-browser and expo-linking, the reference
+ * app adds react-native-webview) — and a bundle built for one host may keep
+ * such a module external and only use it on a path another host never takes.
+ * Failing those at evaluation would break already-deployed bundles we have no
+ * inventory of, and there is no single right name to point the author at.
+ */
+
+/** The one SDK module name a bundle can require (values and types alike). */
+export const PLUGIN_SDK_MODULE = '@adas/plugin-sdk';
+
+/**
+ * The by-name refusal for a require of an SDK-namespace name the shim will
+ * never satisfy, or null when the name is the SDK itself or not the SDK's.
+ */
+export function sdkModuleRefusal(name: string): string | null {
+  if (name === PLUGIN_SDK_MODULE) return null;
+  if (!name.startsWith('@ateam-ai-mobile/') && !name.startsWith('@adas/')) return null;
+  return (
+    `a plugin bundle required '${name}', which does not exist inside a bundle. ` +
+    `Import from '${PLUGIN_SDK_MODULE}' instead — it is the only SDK module a bundle can require ` +
+    `(values and types alike), and the one to keep external when building. ` +
+    `'@ateam-ai-mobile/*' are the host app's packages, not the plugin's.`
+  );
+}

package/src/bundles/bundleUrl.ts

@@ -0,0 +1,41 @@
+/**
+ * THE bundle URL of a plugin: the one place it is spelled.
+ *
+ * Core serves a plugin's React Native bundle at
+ * `/api/ui-plugins/<pluginId>/bundle.js`, where the id is URL-encoded because
+ * plugin ids contain ':' (`mcp:<connector>:<plugin>`). The bundle manager keys
+ * everything it holds by this string: evaluated modules, in-flight downloads and
+ * the disk index. To it, two spellings of one plugin's URL are two plugins, which
+ * means two downloads, two evaluations and two separate copies of module state.
+ *
+ * That happened (MGAP-C8). The rendered surface derived the encoded route, while
+ * the device-tool loader (6294cc3) used the manifest's `bundleUrl`, which Core
+ * fills in UNENCODED. A plugin that was on screen and also had device tools ran
+ * as two module instances, and its tools never saw its UI's state.
+ *
+ * So the URL is DERIVED from the plugin id and never read from a manifest (a
+ * connector-supplied URL is ignored, as in ea435149). Every path that builds a
+ * plugin's bundle URL, or looks one up, calls this function.
+ */
+export function pluginBundleUrl(pluginId: string): string {
+  return `/api/ui-plugins/${encodeURIComponent(pluginId)}/bundle.js`;
+}
+
+/**
+ * Is `url` this plugin's bundle URL, however the id is spelled in it?
+ *
+ * Core's manifest writes the id unencoded (`/api/ui-plugins/mcp:c:p/bundle.js`).
+ * That is the same route as `pluginBundleUrl(pluginId)`, but it is not a key the
+ * SDK may use. The check compares decoded forms, so it asks "same route?" without
+ * parsing the URL. A URL that cannot be decoded is not a match (fail closed).
+ */
+export function isPluginBundleUrl(url: unknown, pluginId: string): boolean {
+  if (typeof url !== 'string') return false;
+  const canonical = pluginBundleUrl(pluginId);
+  if (url === canonical) return true;
+  try {
+    return decodeURIComponent(url) === decodeURIComponent(canonical);
+  } catch {
+    return false;
+  }
+}

package/src/bundles/storage.ts

@@ -5,6 +5,8 @@
  * default is in-memory (bundles re-download per app session — correct,
  * just slower on cold start).
  */
+import type { PluginGrants } from '../pluginRuntime';
+import { pluginBundleUrl, isPluginBundleUrl } from './bundleUrl';
 
 export interface BundleCacheEntry {
   localPath: string;
@@ -27,6 +29,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;
 }
 
 /**
@@ -55,6 +75,57 @@ export function selectOwnedCacheEntries<T extends { tenant?: string }>(
   return (entries || []).filter((e) => !!e && e.tenant === tenant);
 }
 
+/**
+ * Read the disk index with every entry filed under its plugin's ONE bundle URL
+ * (pluginBundleUrl). The SDK reads the index only through this function.
+ *
+ * Before MGAP-C8, the device-tool loader recorded entries under the manifest's
+ * UNENCODED spelling (`/api/ui-plugins/mcp:c:p/bundle.js`), while the rendered
+ * surface used the encoded one. A device that ran both can therefore hold one
+ * plugin under two keys. Every load now asks for the canonical URL, so an entry
+ * stored under the other spelling would never be read again.
+ *
+ * The decision is to RECOVER such an entry rather than discard it, but only when
+ * it provably is the same bundle. An entry moves to the canonical key only when
+ * both of these hold:
+ *  (a) it carries the trusted declaration that names its plugin. That record
+ *      comes from the manifest, never from the bundle.
+ *  (b) its URL is that plugin's route in another spelling (isPluginBundleUrl).
+ * Its tenant stamp, hash and trusted declaration move with it unchanged. So its
+ * ownership (selectOwnedCacheEntries) and its integrity (the hash is re-checked
+ * at eval) stay exactly as they were. When both spellings hold an entry, the
+ * NEWER one is kept. That is the same last-writer-wins rule one key always had.
+ *
+ * Everything else stays where it is and is never adopted:
+ *  - an entry with no trusted declaration (its plugin is unknown without parsing
+ *    its URL);
+ *  - a URL that is not the plugin's route at all, such as a connector-declared
+ *    URL the old loader followed.
+ * Such an entry is simply never matched. Its plugin downloads once more under
+ * the canonical key, and the hash gate still applies.
+ *
+ * The index is mutated in place (the manager does read-modify-write on it), and
+ * the move reaches disk with the next index write.
+ */
+export async function loadCacheIndex(
+  storage: BundleStorage = getBundleStorage(),
+): Promise<Record<string, BundleCacheEntry>> {
+  const index = (await storage.loadIndex()) || {};
+  for (const [key, entry] of Object.entries(index)) {
+    const pluginId = entry?.trusted?.pluginId;
+    if (!pluginId) continue;
+    const canonical = pluginBundleUrl(pluginId);
+    if (key === canonical) continue;
+    if (!isPluginBundleUrl(key, pluginId) || !isPluginBundleUrl(entry.bundleUrl, pluginId)) continue;
+    delete index[key];
+    const held = index[canonical];
+    if (!held || (entry.timestamp ?? 0) > (held.timestamp ?? 0)) {
+      index[canonical] = { ...entry, bundleUrl: canonical };
+    }
+  }
+  return index;
+}
+
 export interface BundleStorage {
   loadIndex(): Promise<Record<string, BundleCacheEntry>>;
   saveIndex(index: Record<string, BundleCacheEntry>): Promise<void>;

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]);