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

package/dist/index.d.mts

@@ -6,12 +6,15 @@ import { View, TextInput } from 'react-native';
 export { ActivityIndicator, Animated, FlatList, Image, Modal, Platform, Pressable, RefreshControl, ScrollView, SectionList, StyleSheet, Switch, Text, TextInput, TouchableOpacity, View } from 'react-native';
 
 /**
- * @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?
@@ -22,7 +25,7 @@ export { ActivityIndicator, Animated, FlatList, Image, Modal, Platform, Pressabl
  *                         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?"
@@ -31,7 +34,8 @@ export { ActivityIndicator, Animated, FlatList, Image, Modal, Platform, Pressabl
  *                         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
@@ -519,8 +523,19 @@ interface VisualDomain {
 }
 /** FROZEN (API_FREEZE §5, VOCABULARY §"Human Activity Values"). */
 type HumanActivity = 'stationary' | 'walking' | 'running' | 'cycling' | 'driving' | 'unknown';
-/** FROZEN. Independent of HumanActivity — walking+pocket, driving+mounted. */
-type DevicePlacement = 'handheld' | 'pocket' | 'table' | 'mounted' | 'unknown';
+/**
+ * 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.
+ */
+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';
 /**
  * FROZEN. Note `driving` is BOTH an intent here and a HumanActivity value
  * above. The docs define no relationship between the two and do not flag the
@@ -1014,6 +1029,7 @@ declare namespace deviceState {
  *
  * See docs/handoff/SPEC_voice_session_without_the_voice_screen_2026-09-12.md.
  */
+
 /** The session lifecycle — identical vocabulary to the built-in `CallState`. */
 type VoiceState = 'idle' | 'connecting' | 'connected' | 'error';
 /** One line of the conversation. `tool` entries are device/skill tool activity. */
@@ -1022,6 +1038,40 @@ interface VoiceTranscriptEntry {
     text: string;
     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.
+ */
+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.
+ */
+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. */
 interface VoiceSnapshot {
     state: VoiceState;
@@ -1045,13 +1095,18 @@ 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;
@@ -1937,6 +1992,18 @@ interface DeviceToolContext {
     signal?: AbortSignal;
 }
 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.
+ */
+type DeviceToolFailureReason = 'not_found' | 'no_context' | 'timeout' | 'failed';
 interface DeviceToolDefinition {
     /** Domain name, as the catalog and the caller see it. e.g. "guide.observe" */
     name: string;
@@ -2310,7 +2377,7 @@ type DeviceToolOutcome = {
 } | {
     ok: false;
     error: string;
-    reason: 'not_found' | 'no_context' | 'timeout' | 'failed';
+    reason: DeviceToolFailureReason;
 };
 /**
  * Override how a device tool reaches the Device Bridge. Rarely needed — the
@@ -3028,7 +3095,15 @@ declare function supportsNative(manifest: PluginManifest): boolean;
  */
 declare function getNativeComponentId(manifest: PluginManifest): string | null;
 /**
- * Get the native bundle URL from a manifest (if it has native support).
+ * The native bundle URL for a manifest that has a bundle on the server, or null.
+ *
+ * Core writes `bundleUrl` into the manifest only when the connector's bundle
+ * exists, so its PRESENCE says "there is a bundle". Its SPELLING is not used:
+ * Core writes the id unencoded, and a connector could inject any URL. The URL
+ * returned is always the one derivation, pluginBundleUrl(manifest.id), the same
+ * one the rendered surface uses. Returning the manifest's own string (6294cc3)
+ * gave the device-tool loader a second spelling, so one plugin downloaded and
+ * evaluated twice, as two module instances (MGAP-C8).
  */
 declare function getNativeBundleUrl(manifest: PluginManifest): string | null;
 /**
@@ -3063,6 +3138,27 @@ declare function getPlugin(pluginId: string): Promise<PluginManifest | null>;
  */
 declare function resolvePluginUrl(manifest: PluginManifest, tenant?: string): string;
 
+/**
+ * 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.
+ */
+declare function pluginBundleUrl(pluginId: string): string;
+
 interface SurfaceDrawerProps {
     visible: boolean;
     onClose: () => void;
@@ -3210,4 +3306,4 @@ declare function isInlineSurface(m: SurfaceManifest): m is InlineSurfaceManifest
 
 declare function SurfaceDispatcher(): react_jsx_runtime.JSX.Element;
 
-export { ActionButton, type ActivitySnapshot, AdaOrb, type AdaOrbState, Badge, type BiometricsAPI, type BiometricsAPIv2, type BluetoothAPI, type BluetoothDevice, type Bridge, type BundleCacheEntry, type BundleStorage, type CameraAPI, CameraPreview, type CameraPreviewProps, type CapabilitySnapshot, type CapabilityStatus, Card, type Confidence, type ConnectivityAPI, type ConnectivitySnapshot, type CookiesAPI, type DeviceBridgeDomain, type DeviceContextSnapshot, type DeviceState, type DeviceToolContext, type DeviceToolDefinition, type DeviceToolFn, type DeviceToolOutcome, type DeviceToolSummary, type DeviceToolsAction, type DeviceToolsSessionDeps, EmptyState, type EnvironmentSnapshot, ErrorState, type FileSystemAPI, type Freshness, type HapticsAPI, type InlineSurfaceManifest, type InteractionSnapshot, ListItem, type LoadedBundleInfo, type LoadedBundleSource, LoadingState, type LocationAPI, type MapsAPI, type MapsAddress, type MapsCoordinate, type MapsPlace, type MapsRoute, type MapsRouteStep, MemoryBundleStorage, type MountSurfaceManifest, type NativeCapabilities$1 as NativeCapabilities, type NfcAPI, type NotificationsAPI, PLATFORM_VOICE_CALLER, type PluginManifest as PlatformPluginManifest, type PluginBridge, type PluginContext, type PluginGrants, type PluginHooks$1 as PluginHooks, type PluginManifest$1 as PluginManifest, type PluginNative, type PluginProps, type PluginRuntimeProps, type PluginRuntimeSource, PluginSDK, type PluginSummary, type PluginSurfaceMeta, type RegisteredPlugin, type RegisteredServicePlugin, type RegisteredToolsPlugin, type RegisteredUIPlugin, type RemotePlugin, type RenderMode, type ScannerAPI, SearchBar, type SessionSnapshot, type SharingAPI, type SpatialEvent, type SpatialIntent, type SpatialPoint, type SpatialSnapshot, type SpatialStateEvent, type StateEvent, type StateListener, type StateQuality, type StorageAPI, type Subscription, SurfaceCard, type SurfaceCardProps, SurfaceDispatcher, SurfaceDrawer, type SurfaceDrawerProps, SurfaceFullscreen, type SurfaceFullscreenProps, type SurfaceManifest, type SurfacePlacement, type SurfaceType, type SurfaceVisibility, TabBar, type ThemeTokens, type TrustedToolDeclaration, type VisionAPI, type VisionFrameQuality, type VisionLabel, type VisionObject, type VisionText, type VisualSnapshot, type VoiceAPI, type VoiceCaller, type VoiceEvent, type VoicePersona, type VoiceSessionProvider, type VoiceSnapshot, type VoiceStartOptions, type VoiceState, type VoiceSubscription, type VoiceTranscriptEntry, type WebViewCookie, __resetSessionSyncForTest, bundleManager, callDeviceTool, clearDeviceTools, createNativeBridge, deviceState as deviceStateV2, deviceToolsActionForSession, ensureDeviceToolsLoaded, explainCapability, gateDeviceState, gatePluginNative, gateVoice, getCameraPreviewProvider, getHaptics, getNativeBundleHash, getNativeBundleUrl, getNativeComponentId, getPlugin, getPluginNative, handleServerDeviceToolCall, hasDeviceTool, implementedStateDomains, implementedVoice, isActionable, isDeviceToolCommand, isInlineSurface, isMountSurface, listDeviceTools, listPlugins, nativePluginRegistry, neverObserved, register, registerBundleModules, registerDeviceTools, registerNativePlugin, registerPlatformDeviceTools, registerService, registerTools, resetDeviceToolLoader, resolvePluginGrants, resolvePluginRuntimeProps, resolvePluginUrl, setBundleStorage, setCameraPreviewProvider, setDeviceStateProvider, setDeviceToolContextProvider, setDeviceToolResultPoster, setHapticsProvider, setPluginNativeProvider, setPluginThemeColors, setVoiceProvider, supportsNative, supportsWebView, syncDeviceToolsForSession, unregisterDeviceTools, unregisterNativePlugin, useApi, useNativeBridge, usePlugin, usePluginTheme, useRemotePlugins, useSurfaceStore };
+export { ActionButton, type ActivitySnapshot, AdaOrb, type AdaOrbState, Badge, type BiometricsAPI, type BiometricsAPIv2, type BluetoothAPI, type BluetoothDevice, type Bridge, type BundleCacheEntry, type BundleStorage, type CameraAPI, CameraPreview, type CameraPreviewProps, type CapabilitySnapshot, type CapabilityStatus, Card, type Confidence, type ConnectivityAPI, type ConnectivitySnapshot, type CookiesAPI, type DeviceBridgeDomain, type DeviceContextSnapshot, type DeviceState, type DeviceToolContext, type DeviceToolDefinition, type DeviceToolFailureReason, type DeviceToolFn, type DeviceToolOutcome, type DeviceToolSummary, type DeviceToolsAction, type DeviceToolsSessionDeps, EmptyState, type EnvironmentSnapshot, ErrorState, type FileSystemAPI, type Freshness, type HapticsAPI, type InlineSurfaceManifest, type InteractionSnapshot, ListItem, type LoadedBundleInfo, type LoadedBundleSource, LoadingState, type LocationAPI, type MapsAPI, type MapsAddress, type MapsCoordinate, type MapsPlace, type MapsRoute, type MapsRouteStep, MemoryBundleStorage, type MountSurfaceManifest, type NativeCapabilities$1 as NativeCapabilities, type NfcAPI, type NotificationsAPI, PLATFORM_VOICE_CALLER, type PluginManifest as PlatformPluginManifest, type PluginBridge, type PluginContext, type PluginGrants, type PluginHooks$1 as PluginHooks, type PluginManifest$1 as PluginManifest, type PluginNative, type PluginProps, type PluginRuntimeProps, type PluginRuntimeSource, PluginSDK, type PluginSummary, type PluginSurfaceMeta, type RegisteredPlugin, type RegisteredServicePlugin, type RegisteredToolsPlugin, type RegisteredUIPlugin, type RemotePlugin, type RenderMode, type ScannerAPI, SearchBar, type SessionSnapshot, type SharingAPI, type SpatialEvent, type SpatialIntent, type SpatialPoint, type SpatialSnapshot, type SpatialStateEvent, type StateEvent, type StateListener, type StateQuality, type StorageAPI, type Subscription, SurfaceCard, type SurfaceCardProps, SurfaceDispatcher, SurfaceDrawer, type SurfaceDrawerProps, SurfaceFullscreen, type SurfaceFullscreenProps, type SurfaceManifest, type SurfacePlacement, type SurfaceType, type SurfaceVisibility, TabBar, type ThemeTokens, type TrustedToolDeclaration, type VisionAPI, type VisionFrameQuality, type VisionLabel, type VisionObject, type VisionText, type VisualSnapshot, type VoiceAPI, type VoiceCaller, type VoiceDeviceToolCall, type VoiceDeviceToolReason, type VoiceEvent, type VoicePersona, type VoiceSessionProvider, type VoiceSnapshot, type VoiceStartOptions, type VoiceState, type VoiceSubscription, type VoiceTranscriptEntry, type WebViewCookie, __resetSessionSyncForTest, bundleManager, callDeviceTool, clearDeviceTools, createNativeBridge, deviceState as deviceStateV2, deviceToolsActionForSession, ensureDeviceToolsLoaded, explainCapability, gateDeviceState, gatePluginNative, gateVoice, getCameraPreviewProvider, getHaptics, getNativeBundleHash, getNativeBundleUrl, getNativeComponentId, getPlugin, getPluginNative, handleServerDeviceToolCall, hasDeviceTool, implementedStateDomains, implementedVoice, isActionable, isDeviceToolCommand, isInlineSurface, isMountSurface, listDeviceTools, listPlugins, nativePluginRegistry, neverObserved, pluginBundleUrl, register, registerBundleModules, registerDeviceTools, registerNativePlugin, registerPlatformDeviceTools, registerService, registerTools, resetDeviceToolLoader, resolvePluginGrants, resolvePluginRuntimeProps, resolvePluginUrl, setBundleStorage, setCameraPreviewProvider, setDeviceStateProvider, setDeviceToolContextProvider, setDeviceToolResultPoster, setHapticsProvider, setPluginNativeProvider, setPluginThemeColors, setVoiceProvider, supportsNative, supportsWebView, syncDeviceToolsForSession, unregisterDeviceTools, unregisterNativePlugin, useApi, useNativeBridge, usePlugin, usePluginTheme, useRemotePlugins, useSurfaceStore };

package/dist/index.d.ts

@@ -6,12 +6,15 @@ import { View, TextInput } from 'react-native';
 export { ActivityIndicator, Animated, FlatList, Image, Modal, Platform, Pressable, RefreshControl, ScrollView, SectionList, StyleSheet, Switch, Text, TextInput, TouchableOpacity, View } from 'react-native';
 
 /**
- * @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?
@@ -22,7 +25,7 @@ export { ActivityIndicator, Animated, FlatList, Image, Modal, Platform, Pressabl
  *                         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?"
@@ -31,7 +34,8 @@ export { ActivityIndicator, Animated, FlatList, Image, Modal, Platform, Pressabl
  *                         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
@@ -519,8 +523,19 @@ interface VisualDomain {
 }
 /** FROZEN (API_FREEZE §5, VOCABULARY §"Human Activity Values"). */
 type HumanActivity = 'stationary' | 'walking' | 'running' | 'cycling' | 'driving' | 'unknown';
-/** FROZEN. Independent of HumanActivity — walking+pocket, driving+mounted. */
-type DevicePlacement = 'handheld' | 'pocket' | 'table' | 'mounted' | 'unknown';
+/**
+ * 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.
+ */
+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';
 /**
  * FROZEN. Note `driving` is BOTH an intent here and a HumanActivity value
  * above. The docs define no relationship between the two and do not flag the
@@ -1014,6 +1029,7 @@ declare namespace deviceState {
  *
  * See docs/handoff/SPEC_voice_session_without_the_voice_screen_2026-09-12.md.
  */
+
 /** The session lifecycle — identical vocabulary to the built-in `CallState`. */
 type VoiceState = 'idle' | 'connecting' | 'connected' | 'error';
 /** One line of the conversation. `tool` entries are device/skill tool activity. */
@@ -1022,6 +1038,40 @@ interface VoiceTranscriptEntry {
     text: string;
     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.
+ */
+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.
+ */
+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. */
 interface VoiceSnapshot {
     state: VoiceState;
@@ -1045,13 +1095,18 @@ 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;
@@ -1937,6 +1992,18 @@ interface DeviceToolContext {
     signal?: AbortSignal;
 }
 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.
+ */
+type DeviceToolFailureReason = 'not_found' | 'no_context' | 'timeout' | 'failed';
 interface DeviceToolDefinition {
     /** Domain name, as the catalog and the caller see it. e.g. "guide.observe" */
     name: string;
@@ -2310,7 +2377,7 @@ type DeviceToolOutcome = {
 } | {
     ok: false;
     error: string;
-    reason: 'not_found' | 'no_context' | 'timeout' | 'failed';
+    reason: DeviceToolFailureReason;
 };
 /**
  * Override how a device tool reaches the Device Bridge. Rarely needed — the
@@ -3028,7 +3095,15 @@ declare function supportsNative(manifest: PluginManifest): boolean;
  */
 declare function getNativeComponentId(manifest: PluginManifest): string | null;
 /**
- * Get the native bundle URL from a manifest (if it has native support).
+ * The native bundle URL for a manifest that has a bundle on the server, or null.
+ *
+ * Core writes `bundleUrl` into the manifest only when the connector's bundle
+ * exists, so its PRESENCE says "there is a bundle". Its SPELLING is not used:
+ * Core writes the id unencoded, and a connector could inject any URL. The URL
+ * returned is always the one derivation, pluginBundleUrl(manifest.id), the same
+ * one the rendered surface uses. Returning the manifest's own string (6294cc3)
+ * gave the device-tool loader a second spelling, so one plugin downloaded and
+ * evaluated twice, as two module instances (MGAP-C8).
  */
 declare function getNativeBundleUrl(manifest: PluginManifest): string | null;
 /**
@@ -3063,6 +3138,27 @@ declare function getPlugin(pluginId: string): Promise<PluginManifest | null>;
  */
 declare function resolvePluginUrl(manifest: PluginManifest, tenant?: string): string;
 
+/**
+ * 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.
+ */
+declare function pluginBundleUrl(pluginId: string): string;
+
 interface SurfaceDrawerProps {
     visible: boolean;
     onClose: () => void;
@@ -3210,4 +3306,4 @@ declare function isInlineSurface(m: SurfaceManifest): m is InlineSurfaceManifest
 
 declare function SurfaceDispatcher(): react_jsx_runtime.JSX.Element;
 
-export { ActionButton, type ActivitySnapshot, AdaOrb, type AdaOrbState, Badge, type BiometricsAPI, type BiometricsAPIv2, type BluetoothAPI, type BluetoothDevice, type Bridge, type BundleCacheEntry, type BundleStorage, type CameraAPI, CameraPreview, type CameraPreviewProps, type CapabilitySnapshot, type CapabilityStatus, Card, type Confidence, type ConnectivityAPI, type ConnectivitySnapshot, type CookiesAPI, type DeviceBridgeDomain, type DeviceContextSnapshot, type DeviceState, type DeviceToolContext, type DeviceToolDefinition, type DeviceToolFn, type DeviceToolOutcome, type DeviceToolSummary, type DeviceToolsAction, type DeviceToolsSessionDeps, EmptyState, type EnvironmentSnapshot, ErrorState, type FileSystemAPI, type Freshness, type HapticsAPI, type InlineSurfaceManifest, type InteractionSnapshot, ListItem, type LoadedBundleInfo, type LoadedBundleSource, LoadingState, type LocationAPI, type MapsAPI, type MapsAddress, type MapsCoordinate, type MapsPlace, type MapsRoute, type MapsRouteStep, MemoryBundleStorage, type MountSurfaceManifest, type NativeCapabilities$1 as NativeCapabilities, type NfcAPI, type NotificationsAPI, PLATFORM_VOICE_CALLER, type PluginManifest as PlatformPluginManifest, type PluginBridge, type PluginContext, type PluginGrants, type PluginHooks$1 as PluginHooks, type PluginManifest$1 as PluginManifest, type PluginNative, type PluginProps, type PluginRuntimeProps, type PluginRuntimeSource, PluginSDK, type PluginSummary, type PluginSurfaceMeta, type RegisteredPlugin, type RegisteredServicePlugin, type RegisteredToolsPlugin, type RegisteredUIPlugin, type RemotePlugin, type RenderMode, type ScannerAPI, SearchBar, type SessionSnapshot, type SharingAPI, type SpatialEvent, type SpatialIntent, type SpatialPoint, type SpatialSnapshot, type SpatialStateEvent, type StateEvent, type StateListener, type StateQuality, type StorageAPI, type Subscription, SurfaceCard, type SurfaceCardProps, SurfaceDispatcher, SurfaceDrawer, type SurfaceDrawerProps, SurfaceFullscreen, type SurfaceFullscreenProps, type SurfaceManifest, type SurfacePlacement, type SurfaceType, type SurfaceVisibility, TabBar, type ThemeTokens, type TrustedToolDeclaration, type VisionAPI, type VisionFrameQuality, type VisionLabel, type VisionObject, type VisionText, type VisualSnapshot, type VoiceAPI, type VoiceCaller, type VoiceEvent, type VoicePersona, type VoiceSessionProvider, type VoiceSnapshot, type VoiceStartOptions, type VoiceState, type VoiceSubscription, type VoiceTranscriptEntry, type WebViewCookie, __resetSessionSyncForTest, bundleManager, callDeviceTool, clearDeviceTools, createNativeBridge, deviceState as deviceStateV2, deviceToolsActionForSession, ensureDeviceToolsLoaded, explainCapability, gateDeviceState, gatePluginNative, gateVoice, getCameraPreviewProvider, getHaptics, getNativeBundleHash, getNativeBundleUrl, getNativeComponentId, getPlugin, getPluginNative, handleServerDeviceToolCall, hasDeviceTool, implementedStateDomains, implementedVoice, isActionable, isDeviceToolCommand, isInlineSurface, isMountSurface, listDeviceTools, listPlugins, nativePluginRegistry, neverObserved, register, registerBundleModules, registerDeviceTools, registerNativePlugin, registerPlatformDeviceTools, registerService, registerTools, resetDeviceToolLoader, resolvePluginGrants, resolvePluginRuntimeProps, resolvePluginUrl, setBundleStorage, setCameraPreviewProvider, setDeviceStateProvider, setDeviceToolContextProvider, setDeviceToolResultPoster, setHapticsProvider, setPluginNativeProvider, setPluginThemeColors, setVoiceProvider, supportsNative, supportsWebView, syncDeviceToolsForSession, unregisterDeviceTools, unregisterNativePlugin, useApi, useNativeBridge, usePlugin, usePluginTheme, useRemotePlugins, useSurfaceStore };
+export { ActionButton, type ActivitySnapshot, AdaOrb, type AdaOrbState, Badge, type BiometricsAPI, type BiometricsAPIv2, type BluetoothAPI, type BluetoothDevice, type Bridge, type BundleCacheEntry, type BundleStorage, type CameraAPI, CameraPreview, type CameraPreviewProps, type CapabilitySnapshot, type CapabilityStatus, Card, type Confidence, type ConnectivityAPI, type ConnectivitySnapshot, type CookiesAPI, type DeviceBridgeDomain, type DeviceContextSnapshot, type DeviceState, type DeviceToolContext, type DeviceToolDefinition, type DeviceToolFailureReason, type DeviceToolFn, type DeviceToolOutcome, type DeviceToolSummary, type DeviceToolsAction, type DeviceToolsSessionDeps, EmptyState, type EnvironmentSnapshot, ErrorState, type FileSystemAPI, type Freshness, type HapticsAPI, type InlineSurfaceManifest, type InteractionSnapshot, ListItem, type LoadedBundleInfo, type LoadedBundleSource, LoadingState, type LocationAPI, type MapsAPI, type MapsAddress, type MapsCoordinate, type MapsPlace, type MapsRoute, type MapsRouteStep, MemoryBundleStorage, type MountSurfaceManifest, type NativeCapabilities$1 as NativeCapabilities, type NfcAPI, type NotificationsAPI, PLATFORM_VOICE_CALLER, type PluginManifest as PlatformPluginManifest, type PluginBridge, type PluginContext, type PluginGrants, type PluginHooks$1 as PluginHooks, type PluginManifest$1 as PluginManifest, type PluginNative, type PluginProps, type PluginRuntimeProps, type PluginRuntimeSource, PluginSDK, type PluginSummary, type PluginSurfaceMeta, type RegisteredPlugin, type RegisteredServicePlugin, type RegisteredToolsPlugin, type RegisteredUIPlugin, type RemotePlugin, type RenderMode, type ScannerAPI, SearchBar, type SessionSnapshot, type SharingAPI, type SpatialEvent, type SpatialIntent, type SpatialPoint, type SpatialSnapshot, type SpatialStateEvent, type StateEvent, type StateListener, type StateQuality, type StorageAPI, type Subscription, SurfaceCard, type SurfaceCardProps, SurfaceDispatcher, SurfaceDrawer, type SurfaceDrawerProps, SurfaceFullscreen, type SurfaceFullscreenProps, type SurfaceManifest, type SurfacePlacement, type SurfaceType, type SurfaceVisibility, TabBar, type ThemeTokens, type TrustedToolDeclaration, type VisionAPI, type VisionFrameQuality, type VisionLabel, type VisionObject, type VisionText, type VisualSnapshot, type VoiceAPI, type VoiceCaller, type VoiceDeviceToolCall, type VoiceDeviceToolReason, type VoiceEvent, type VoicePersona, type VoiceSessionProvider, type VoiceSnapshot, type VoiceStartOptions, type VoiceState, type VoiceSubscription, type VoiceTranscriptEntry, type WebViewCookie, __resetSessionSyncForTest, bundleManager, callDeviceTool, clearDeviceTools, createNativeBridge, deviceState as deviceStateV2, deviceToolsActionForSession, ensureDeviceToolsLoaded, explainCapability, gateDeviceState, gatePluginNative, gateVoice, getCameraPreviewProvider, getHaptics, getNativeBundleHash, getNativeBundleUrl, getNativeComponentId, getPlugin, getPluginNative, handleServerDeviceToolCall, hasDeviceTool, implementedStateDomains, implementedVoice, isActionable, isDeviceToolCommand, isInlineSurface, isMountSurface, listDeviceTools, listPlugins, nativePluginRegistry, neverObserved, pluginBundleUrl, register, registerBundleModules, registerDeviceTools, registerNativePlugin, registerPlatformDeviceTools, registerService, registerTools, resetDeviceToolLoader, resolvePluginGrants, resolvePluginRuntimeProps, resolvePluginUrl, setBundleStorage, setCameraPreviewProvider, setDeviceStateProvider, setDeviceToolContextProvider, setDeviceToolResultPoster, setHapticsProvider, setPluginNativeProvider, setPluginThemeColors, setVoiceProvider, supportsNative, supportsWebView, syncDeviceToolsForSession, unregisterDeviceTools, unregisterNativePlugin, useApi, useNativeBridge, usePlugin, usePluginTheme, useRemotePlugins, useSurfaceStore };