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

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

@@ -6,6 +6,7 @@
  * just slower on cold start).
  */
 import type { PluginGrants } from '../pluginRuntime';
+import { pluginBundleUrl, isPluginBundleUrl } from './bundleUrl';
 
 export interface BundleCacheEntry {
   localPath: string;
@@ -74,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/hooks/usePlugin.ts

@@ -16,6 +16,7 @@ import { nativePluginRegistry } from '../host';
 import { resolvePluginGrants } from '../pluginRuntime';
 import type { NativeCapabilities, RegisteredUIPlugin } from '../sdk/types';
 import type { DeviceBridgeDomain } from '../sdk/device-state';
+import { pluginBundleUrl } from '../bundles/bundleUrl';
 
 interface PluginManifestLike {
   version?: string;
@@ -64,7 +65,7 @@ function extractBundleUrl(pluginId: string, manifest: PluginManifestLike): { url
   const hasNativeComponent = !!(render.reactNative?.component || render.component);
   if (hasNativeComponent) {
     return {
-      url: `/api/ui-plugins/${encodeURIComponent(pluginId)}/bundle.js`,
+      url: pluginBundleUrl(pluginId),
       source: injected ? 'ignored-explicit' : 'derived-default',
       ...(injected && { ignored: injected }),
     };

package/src/index.ts

@@ -19,43 +19,14 @@ 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.
+// rather than throwing. Its plugin-facing types and the isActionable /
+// explainCapability helpers come through `export * from './sdk'` above — the
+// plugin SDK is the one place they are listed, because it is the only module a
+// bundle can require. The whole layer is also available under its own path.
 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';
+// The canonical `unknown` freshness the engine's quality module derives from —
+// an ENGINE value (the host's device-state domains), not a plugin one.
+export { neverObserved } from './sdk/device-state';
 
 // Device Bridge v2 host DI — the semantic counterpart of
 // setPluginNativeProvider. Separate module on purpose: the moment the two
@@ -148,6 +119,9 @@ export {
   getNativeBundleUrl,
   getNativeBundleHash,
 } from './api/plugins';
+// The one spelling of a plugin's bundle URL (MGAP-C8) — hosts that build or
+// compare one use this, never their own template.
+export { pluginBundleUrl } from './bundles/bundleUrl';
 export type { PluginSummary, PluginSurfaceMeta } from './api/plugins';
 export type { PluginManifest as PlatformPluginManifest } from './api/plugins';
 

package/src/sdk/CameraPreview.tsx

@@ -1,6 +1,13 @@
 /**
  * CameraPreview — the plugin-facing way to SHOW the user what the camera sees.
  *
+ *   import { CameraPreview } from '@adas/plugin-sdk';
+ *   <CameraPreview native={native} />      // native = the plugin's own props.native
+ *
+ * '@adas/plugin-sdk' is the only SDK module a bundle can require. The same code
+ * is published as '@ateam-ai-mobile/plugin-runtime', but that is the host app's
+ * package: a bundle that requires it fails at evaluation, by name.
+ *
  * WHY THIS EXISTS RATHER THAN HANDING PLUGINS `expo-camera`.
  *
  * The design has exactly two doors to the device: `props.native.*` (mechanical

package/src/sdk/device-state.ts

@@ -1,10 +1,13 @@
 /**
- * @adas/device-state — Device Bridge v2, the SEMANTIC layer.
+ * Device state — Device Bridge v2, the SEMANTIC layer.
  *
- * Intended repo path:
+ * Repo path:
  *   packages/plugin-runtime/src/sdk/device-state.ts
- * Intended module specifier for plugin bundles:
- *   '@adas/device-state'   (NOT '@adas/plugin-sdk')
+ * Module specifier for plugin bundles:
+ *   '@adas/plugin-sdk' — the only SDK module a bundle can require. This file
+ *   once named '@adas/device-state' here (4110943); the require shim never
+ *   resolved it, so a bundle that imported it got `{}` and failed later. It is
+ *   now refused by name at evaluation (bundles/bundleModuleNames.ts).
  *
  * ─────────────────────────────────────────────────────────────────────────
  * WHICH LAYER AM I IN?
@@ -15,7 +18,7 @@
  *                         Returns a BARE value. THROWS when it cannot.
  *                         Declared in the manifest as `capabilities: { camera: true }`
  *                         (the legacy `native: {}` field is still honoured).
- *                         Lives in '@adas/plugin-sdk'.
+ *                         Its types are imported from '@adas/plugin-sdk'.
  *
  *   props.deviceState.*   SEMANTIC. "What is true right now, and how well do
  *                         we know it?"
@@ -24,7 +27,8 @@
  *                         and able to say `unknown` in every field.
  *                         A read NEVER throws for absence.
  *                         Declared in the manifest as `stateDomains: ['visual']`.
- *                         Lives in '@adas/device-state' (this file).
+ *                         Defined in this file; its types and helpers are
+ *                         imported from '@adas/plugin-sdk' too.
  *
  * The two containers are the discriminator. Every semantic call in a plugin
  * begins with the eight characters `deviceState.`; every mechanical call
@@ -655,11 +659,20 @@ export type HumanActivity =
   | 'driving'
   | 'unknown';
 
-/** FROZEN. Independent of HumanActivity — walking+pocket, driving+mounted. */
+/**
+ * FROZEN. Independent of HumanActivity — walking+pocket, driving+mounted.
+ *
+ * What is returned TODAY: `handheld`, `table` and `unknown` only. Do not write
+ * a branch that waits for `pocket` or `mounted`; it will never run. A pocketed
+ * phone shows up in the Visual domain's frame quality (`obstructed: true` /
+ * `exposure: 'dark'`), not here.
+ */
 export type DevicePlacement =
   | 'handheld'
+  /** RESERVED — never returned until the proximity/light sensor is wired. */
   | 'pocket'
   | 'table'
+  /** RESERVED — never returned until Bluetooth/CarPlay mount context is wired. */
   | 'mounted'
   | 'unknown';
 

package/src/sdk/index.ts

@@ -54,6 +54,7 @@ export type {
   DeviceToolContext,
   DeviceToolDefinition,
   DeviceToolFn,
+  DeviceToolFailureReason,
 } from './types';
 
 // Voice — the live conversational SESSION surface (props.voice).
@@ -61,6 +62,8 @@ export type {
   VoiceAPI,
   VoiceState,
   VoiceSnapshot,
+  VoiceDeviceToolCall,
+  VoiceDeviceToolReason,
   VoiceTranscriptEntry,
   VoiceStartOptions,
   VoicePersona,
@@ -73,6 +76,37 @@ export type {
 // provider and its own surfaces call it as this caller. See VoiceSessionProvider.
 export { PLATFORM_VOICE_CALLER } from './voice';
 
+// Device state — the SEMANTIC layer: the types of what `props.deviceState`
+// returns, and the two pure helpers for reading a snapshot. They are here, in
+// the one module a bundle can require, because a bundle has no other SDK name
+// ('@adas/device-state' never resolved, and is refused by name). What keeps the
+// two layers apart is the CONTAINER a call starts with — `deviceState.` vs
+// `device.` — not the import line.
+export type {
+  DeviceState,
+  DeviceBridgeDomain,
+  StateQuality,
+  Freshness,
+  Confidence,
+  VisualSnapshot,
+  SpatialSnapshot,
+  SpatialPoint,
+  SpatialIntent,
+  SpatialEvent,
+  SpatialStateEvent,
+  StateEvent,
+  StateListener,
+  Subscription,
+  ActivitySnapshot,
+  EnvironmentSnapshot,
+  InteractionSnapshot,
+  CapabilitySnapshot,
+  CapabilityStatus,
+  DeviceContextSnapshot,
+  ConnectivitySnapshot,
+} from './device-state';
+export { isActionable, explainCapability } from './device-state';
+
 // RN primitives (plugins import from the SDK, not from react-native)
 export {
   View,

package/src/sdk/types.ts

@@ -767,6 +767,19 @@ export interface DeviceToolContext {
 
 export type DeviceToolFn = (args: any, ctx: DeviceToolContext) => Promise<any> | any;
 
+/**
+ * Why running a device tool produced no result (`callDeviceTool`'s
+ * `{ ok: false, reason }`). The one list: the registry returns these, and the
+ * voice snapshot's `lastDeviceTool.reason` carries them unchanged.
+ *  - `not_found`  — no tool is registered under that name.
+ *  - `no_context` — the tool's device context could not be built.
+ *  - `timeout`    — the tool did not finish within the call's timeout.
+ *  - `failed`     — the tool threw; the error is its message.
+ * A tool that RETURNS a value has succeeded as far as the platform is concerned,
+ * even if the value describes a failure — throw to report one.
+ */
+export type DeviceToolFailureReason = 'not_found' | 'no_context' | 'timeout' | 'failed';
+
 export interface DeviceToolDefinition {
   /** Domain name, as the catalog and the caller see it. e.g. "guide.observe" */
   name: string;

package/src/sdk/voice.ts

@@ -18,6 +18,7 @@
  *
  * See docs/handoff/SPEC_voice_session_without_the_voice_screen_2026-09-12.md.
  */
+import type { DeviceToolFailureReason } from './types';
 
 /** The session lifecycle — identical vocabulary to the built-in `CallState`. */
 export type VoiceState = 'idle' | 'connecting' | 'connected' | 'error';
@@ -29,6 +30,41 @@ export interface VoiceTranscriptEntry {
   ts: number;
 }
 
+/**
+ * Why a device-tool call the session received did not produce a result.
+ *  - the tool RAN and did not return: `not_found` | `no_context` | `timeout` |
+ *    `failed` (it threw) — see DeviceToolFailureReason;
+ *  - the phone REFUSED it before running: `not_ready` (Core's tool allowset for
+ *    this session had not arrived yet — transient, a retry can succeed) or
+ *    `not_authorized` (not allowed in this session — final);
+ *  - `invalid`: the call itself was malformed (it named no tool, or carried no
+ *    correlationId to answer on) — not run.
+ */
+export type VoiceDeviceToolReason = DeviceToolFailureReason | 'not_ready' | 'not_authorized' | 'invalid';
+
+/**
+ * One finished device-tool call, as `VoiceSnapshot.lastDeviceTool` reports it.
+ * `name` and `at` keep their original meaning, so a reader of just those two is
+ * unaffected.
+ */
+export type VoiceDeviceToolCall = {
+  /** The tool the model called ('' if the call named none — see `invalid`). */
+  name: string;
+  /** Epoch ms the call REACHED the phone (not when it finished — that is at + ms). */
+  at: number;
+  /** Milliseconds from arrival to outcome (≈0 for a refusal). */
+  ms: number;
+} & (
+  | { ok: true; reason: null; error: null }
+  | {
+      ok: false;
+      reason: VoiceDeviceToolReason;
+      /** What went wrong, clipped to 200 characters: tool errors can echo the
+       *  call's arguments, which may carry what the user said. */
+      error: string;
+    }
+);
+
 /** A point-in-time read of the session — what a reasoning loop polls. */
 export interface VoiceSnapshot {
   state: VoiceState;
@@ -52,10 +88,18 @@ export interface VoiceSnapshot {
   /** The last error, if `state === 'error'`; also carries a refusal reason when
    *  this surface was handed to a plugin that did not declare `voice`. */
   lastError: string | null;
-  /** The most recent LOCAL device-tool call the model made through the session
-   *  (name + epoch ms), or null if none yet. Diagnostic: proves whether the
-   *  model's call_device_tool actually reached the phone vs was never made. */
-  lastDeviceTool: { name: string; at: number } | null;
+  /**
+   * The most recently FINISHED device-tool call the model made through this
+   * session, with its outcome — or null if none has finished yet. Set once the
+   * outcome is known (ran, refused, malformed, threw, timed out), never on
+   * arrival, so a refused call can no longer look like one that ran.
+   *
+   * SCOPED to the caller: a plugin sees only calls to tools IT registered (never
+   * another solution's tool names or errors, even on its own call); the platform
+   * sees every call. Cleared when the session ends or a new one starts.
+   * Diagnostic — every solution's debug view gets "why did that call fail" free.
+   */
+  lastDeviceTool: VoiceDeviceToolCall | null;
   /** The sessionId the Core allowset is bound to. Diagnostic: authorization
    *  requires it to equal `sessionId`; a mismatch is why tools refuse. */
   authorizedSessionId: string | null;

package/src/tools/loader.ts

@@ -13,7 +13,7 @@
 import { listPlugins, getPlugin, getNativeBundleUrl, getNativeBundleHash } from '../api/plugins';
 import { bundleManager } from '../bundles/bundleManager';
 import { listDeviceTools } from './registry';
-import { getBundleStorage, selectOwnedCacheEntries } from '../bundles/storage';
+import { getBundleStorage, loadCacheIndex, selectOwnedCacheEntries } from '../bundles/storage';
 import { resolvePluginGrants } from '../pluginRuntime';
 import { getTenant } from '@ateam-ai-mobile/core';
 
@@ -142,7 +142,9 @@ export async function ensureDeviceToolsLoaded({ force = false } = {}): Promise<s
  */
 async function loadFromDiskCache(): Promise<string[]> {
   try {
-    const index = await getBundleStorage().loadIndex();
+    // Canonical keys only (loadCacheIndex): an entry an older build filed under
+    // the manifest's unencoded spelling is recovered under pluginBundleUrl.
+    const index = await loadCacheIndex(getBundleStorage());
     const entries = Object.values(index || {});
     if (entries.length === 0) return [];
 

package/src/tools/registry.ts

@@ -15,7 +15,7 @@
 import { createNativeBridge } from '../bridge/native';
 import { getPluginNative, gatePluginNative } from '../host';
 import { gateDeviceState, withoutSubscribe } from '../deviceStateHost';
-import type { DeviceToolContext, DeviceToolDefinition, NativeCapabilities } from '../sdk/types';
+import type { DeviceToolContext, DeviceToolDefinition, DeviceToolFailureReason, NativeCapabilities } from '../sdk/types';
 import type { DeviceBridgeDomain } from '../sdk/device-state';
 
 export interface DeviceToolSummary {
@@ -27,7 +27,7 @@ export interface DeviceToolSummary {
 
 export type DeviceToolOutcome =
   | { ok: true; result: any }
-  | { ok: false; error: string; reason: 'not_found' | 'no_context' | 'timeout' | 'failed' };
+  | { ok: false; error: string; reason: DeviceToolFailureReason };
 
 interface Entry {
   pluginId: string;