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

package/dist/index.d.mts

@@ -20,7 +20,8 @@ export { ActivityIndicator, Animated, FlatList, Image, Modal, Platform, Pressabl
  *                         VERB names: takePhoto, getCurrent, scanBarcode,
  *                         readOnce, authenticate, pickImage.
  *                         Returns a BARE value. THROWS when it cannot.
- *                         Declared in the manifest as `native: { camera: true }`.
+ *                         Declared in the manifest as `capabilities: { camera: true }`
+ *                         (the legacy `native: {}` field is still honoured).
  *                         Lives in '@adas/plugin-sdk'.
  *
  *   props.deviceState.*   SEMANTIC. "What is true right now, and how well do
@@ -117,17 +118,19 @@ type RestrictionState = 'none' | 'backgroundRestricted' | 'systemRestricted' | '
  * never raw sensor streams." If you find yourself wanting an event per frame
  * or per GPS fix, you are in the wrong layer.
  */
-interface StateEvent<TName extends string = string> {
+interface StateEvent<TName extends string = string, TPayload = unknown> {
     domain: DeviceBridgeDomain;
     name: TName;
     /** Epoch ms. */
     timestamp: number;
     /**
      * OPEN: per-event payload schemas are not specified anywhere in the three
-     * design docs. Typed `unknown` rather than `any` so a consumer is forced to
-     * narrow it rather than read a field that may not exist.
+     * design docs. Defaults to `unknown` rather than `any` so a consumer is forced
+     * to narrow it rather than read a field that may not exist. A domain that
+     * decides its schemas (spatial — see `SpatialStateEvent`) passes `TPayload`,
+     * which is the freeze's own second parameter, dropped here until one did.
      */
-    payload?: unknown;
+    payload?: TPayload;
 }
 interface Subscription {
     unsubscribe(): void;
@@ -141,9 +144,17 @@ type StateListener<TName extends string = string> = (event: StateEvent<TName>) =
  * connectivity, capability, interaction and environment only. Rather than mint
  * names those docs deliberately did not mint, their events are typed against
  * the naming RULE. A wrong-shaped name is a compile error; the specific
- * vocabulary stays open, as the docs left it.
+ * vocabulary stays open, as the docs left it — except where a DECISION closes
+ * it (spatial, see `SpatialEvent`), and that list is checked against the rule
+ * through `AssertConforming`.
  */
 type ConformingEventName = `${string}Changed` | `${string}Started` | `${string}Stopped` | `${string}Available` | `${string}Unavailable` | `${string}StateStale`;
+/**
+ * A closed list of names, checked against the naming rule at compile time.
+ * Wrap a decided vocabulary in this and a name like `turnCompleted` stops
+ * compiling instead of reaching a plugin.
+ */
+type AssertConforming<T extends ConformingEventName> = T;
 /** FROZEN (API_FREEZE §12). */
 type DeviceBridgeErrorCode = 'UNSUPPORTED' | 'PERMISSION_DENIED' | 'RESTRICTED' | 'BUSY' | 'TEMPORARILY_UNAVAILABLE' | 'STALE' | 'TIMEOUT' | 'CANCELLED' | 'INTERNAL';
 /**
@@ -272,12 +283,89 @@ interface SpatialSnapshot {
     };
     quality: StateQuality;
 }
+/**
+ * DECISION (not frozen) — the spatial event vocabulary. Six names, all ending
+ * in a suffix the naming rule allows, which `AssertConforming` enforces.
+ *
+ * Drawn from the architecture doc's spatial candidates (meaningful movement,
+ * meaningful turn, location quality degraded/recovered, state became stale)
+ * and named after the SNAPSHOT fields they report, so an event and a read use
+ * one vocabulary: `lastMeaningfulTurnChanged` is `changes.lastMeaningfulTurnDeg`
+ * changing. The names an earlier note floated (`turnCompleted`, `arrived`,
+ * `headingLost`) are rejected — the first two fail the rule, and "arrived" is a
+ * destination, which the vocabulary's Governance puts above Device Bridge.
+ */
+type SpatialEvent = AssertConforming<'movementStarted' | 'movementStopped' | 'lastMeaningfulTurnChanged' | 'positionConfidenceChanged' | 'positionChanged' | 'spatialStateStale'>;
+/** A spatial event: the frozen envelope, with its payload always present. */
+type SpatialEventOf<TName extends SpatialEvent, TPayload> = StateEvent<TName, TPayload> & {
+    domain: 'spatial';
+    payload: TPayload;
+};
+/**
+ * DECISION — what each spatial event carries. Only the facts of the
+ * transition, in the snapshot's own field names; everything else is one
+ * `getSnapshot()` away, which keeps two shapes of the same fact from drifting.
+ *
+ * `timestamp` on the envelope is when the transition was RECOGNISED. Where a
+ * hold delays that on purpose, `since` carries the true onset.
+ */
+type SpatialStateEvent = 
+/** `movement.state` became `moving` and held (navigation: 3 s). */
+SpatialEventOf<'movementStarted', {
+    previous: 'stationary' | 'unknown';
+    speedMps: number | null;
+    bearingDeg: number | null;
+    since: number;
+}>
+/** `moving` → `stationary`, held (navigation: 5 s). Never fired on moving →
+ *  `unknown`: losing the speed is not evidence of stopping. */
+ | SpatialEventOf<'movementStopped', {
+    previous: 'moving';
+    since: number;
+}>
+/** A new completed turn. Signed: positive = clockwise = right. */
+ | SpatialEventOf<'lastMeaningfulTurnChanged', {
+    lastMeaningfulTurnDeg: number;
+    timestamp: number;
+}>
+/** The GPS fix band (high ≤10 m, medium ≤50 m, else low) changed and held.
+ *  The fix alone — a compass calibration change is not a position event. */
+ | SpatialEventOf<'positionConfidenceChanged', {
+    level: ConfidenceLevel;
+    previous: ConfidenceLevel;
+    accuracyM: number | null;
+    direction: 'dropped' | 'recovered';
+}>
+/** Moved at least max(profile floor, 2 × accuracyM) from the last reported
+ *  position, so GPS jitter never fires it. The session's first fix fires
+ *  with `previous: null`. */
+ | SpatialEventOf<'positionChanged', {
+    position: SpatialPoint;
+    previous: SpatialPoint | null;
+    distanceM: number | null;
+}>
+/** `quality.freshness.state` became `stale`. Once; re-armed by a fresh read. */
+ | SpatialEventOf<'spatialStateStale', {
+    observedAt: number | null;
+    ageMs: number | null;
+}>;
 interface SpatialDomain {
     getSnapshot(): Promise<SpatialSnapshot>;
     start(options: StartOptions<SpatialIntent>): Promise<StateSession>;
     stop(sessionId?: string): Promise<void>;
-    /** OPEN: no frozen spatial event vocabulary; rule-conforming names only. */
-    subscribe(listener: StateListener<ConformingEventName>): Subscription;
+    /**
+     * DECISION: the six `SpatialEvent`s, typed per name — narrow on `e.name` and
+     * `e.payload` is that event's shape.
+     *
+     * Events flow only while a spatial session is open; subscribing opens no
+     * sensor. They are derived from the same snapshot `getSnapshot()` returns: a
+     * listener that re-reads inside the callback sees the snapshot its event came
+     * from. A state change must hold, on at least two fixes, before it fires.
+     *
+     * From a device tool's `ctx.deviceState` this refuses (RESTRICTED): a call
+     * has no lifetime to own the listener.
+     */
+    subscribe(listener: (event: SpatialStateEvent) => void): Subscription;
 }
 /** FROZEN (API_FREEZE §4) + VOCABULARY §"Visual Intents". Nine values. */
 type VisualIntent = 'navigation' | 'document' | 'ocr' | 'shopping' | 'inspection' | 'accessibility' | 'stream' | 'highQuality' | 'lowPower';
@@ -841,6 +929,7 @@ interface DeviceToolContextV2Extension {
 type deviceState_ActivityDomain = ActivityDomain;
 type deviceState_ActivityIntent = ActivityIntent;
 type deviceState_ActivitySnapshot = ActivitySnapshot;
+type deviceState_AssertConforming<T extends ConformingEventName> = AssertConforming<T>;
 type deviceState_AvailabilityState = AvailabilityState;
 type deviceState_CapabilityDomain = CapabilityDomain;
 type deviceState_CapabilityEvent = CapabilityEvent;
@@ -877,12 +966,14 @@ type deviceState_MediaHandle = MediaHandle;
 type deviceState_PluginPropsV2Extension = PluginPropsV2Extension;
 type deviceState_RestrictionState = RestrictionState;
 type deviceState_SpatialDomain = SpatialDomain;
+type deviceState_SpatialEvent = SpatialEvent;
 type deviceState_SpatialIntent = SpatialIntent;
 type deviceState_SpatialPoint = SpatialPoint;
 type deviceState_SpatialSnapshot = SpatialSnapshot;
+type deviceState_SpatialStateEvent = SpatialStateEvent;
 type deviceState_StartOptions<TIntent extends string> = StartOptions<TIntent>;
 type deviceState_StateDomainDeclaration = StateDomainDeclaration;
-type deviceState_StateEvent<TName extends string = string> = StateEvent<TName>;
+type deviceState_StateEvent<TName extends string = string, TPayload = unknown> = StateEvent<TName, TPayload>;
 type deviceState_StateListener<TName extends string = string> = StateListener<TName>;
 type deviceState_StateQuality = StateQuality;
 type deviceState_StateSession = StateSession;
@@ -900,7 +991,7 @@ declare const deviceState_explainCapability: typeof explainCapability;
 declare const deviceState_isActionable: typeof isActionable;
 declare const deviceState_neverObserved: typeof neverObserved;
 declare namespace deviceState {
-  export { type deviceState_ActivityDomain as ActivityDomain, type deviceState_ActivityIntent as ActivityIntent, type deviceState_ActivitySnapshot as ActivitySnapshot, type deviceState_AvailabilityState as AvailabilityState, type deviceState_CapabilityDomain as CapabilityDomain, type deviceState_CapabilityEvent as CapabilityEvent, type deviceState_CapabilitySnapshot as CapabilitySnapshot, type deviceState_CapabilityStatus as CapabilityStatus, type deviceState_Confidence as Confidence, type deviceState_ConfidenceLevel as ConfidenceLevel, type deviceState_ConformingEventName as ConformingEventName, type deviceState_ConnectivityDomain as ConnectivityDomain, type deviceState_ConnectivityEvent as ConnectivityEvent, type deviceState_ConnectivityIntent as ConnectivityIntent, type deviceState_ConnectivitySnapshot as ConnectivitySnapshot, type deviceState_DeviceBridgeDomain as DeviceBridgeDomain, deviceState_DeviceBridgeError as DeviceBridgeError, type deviceState_DeviceBridgeErrorCode as DeviceBridgeErrorCode, type deviceState_DeviceBridgeV2 as DeviceBridgeV2, type deviceState_DeviceContextDomain as DeviceContextDomain, type deviceState_DeviceContextSnapshot as DeviceContextSnapshot, type deviceState_DevicePlacement as DevicePlacement, type deviceState_DeviceState as DeviceState, type deviceState_DeviceToolContextV2Extension as DeviceToolContextV2Extension, type deviceState_EnvironmentDomain as EnvironmentDomain, type deviceState_EnvironmentEvent as EnvironmentEvent, type deviceState_EnvironmentIntent as EnvironmentIntent, type deviceState_EnvironmentSnapshot as EnvironmentSnapshot, type deviceState_Freshness as Freshness, type deviceState_FreshnessState as FreshnessState, type deviceState_HumanActivity as HumanActivity, type deviceState_InteractionDomain as InteractionDomain, type deviceState_InteractionEvent as InteractionEvent, type deviceState_InteractionSnapshot as InteractionSnapshot, type deviceState_MediaHandle as MediaHandle, type PermissionState$1 as PermissionState, type deviceState_PluginPropsV2Extension as PluginPropsV2Extension, type deviceState_RestrictionState as RestrictionState, type deviceState_SpatialDomain as SpatialDomain, type deviceState_SpatialIntent as SpatialIntent, type deviceState_SpatialPoint as SpatialPoint, type deviceState_SpatialSnapshot as SpatialSnapshot, type deviceState_StartOptions as StartOptions, type deviceState_StateDomainDeclaration as StateDomainDeclaration, type deviceState_StateEvent as StateEvent, type deviceState_StateListener as StateListener, type deviceState_StateQuality as StateQuality, type deviceState_StateSession as StateSession, type deviceState_StatefulDomain as StatefulDomain, type deviceState_Subscription as Subscription, type deviceState_SupportState as SupportState, type deviceState_VisualCaptureOptions as VisualCaptureOptions, type deviceState_VisualCaptureResult as VisualCaptureResult, type deviceState_VisualDomain as VisualDomain, type deviceState_VisualFrameQuality as VisualFrameQuality, type deviceState_VisualFrameRef as VisualFrameRef, type deviceState_VisualIntent as VisualIntent, type deviceState_VisualSnapshot as VisualSnapshot, deviceState_explainCapability as explainCapability, deviceState_isActionable as isActionable, deviceState_neverObserved as neverObserved };
+  export { type deviceState_ActivityDomain as ActivityDomain, type deviceState_ActivityIntent as ActivityIntent, type deviceState_ActivitySnapshot as ActivitySnapshot, type deviceState_AssertConforming as AssertConforming, type deviceState_AvailabilityState as AvailabilityState, type deviceState_CapabilityDomain as CapabilityDomain, type deviceState_CapabilityEvent as CapabilityEvent, type deviceState_CapabilitySnapshot as CapabilitySnapshot, type deviceState_CapabilityStatus as CapabilityStatus, type deviceState_Confidence as Confidence, type deviceState_ConfidenceLevel as ConfidenceLevel, type deviceState_ConformingEventName as ConformingEventName, type deviceState_ConnectivityDomain as ConnectivityDomain, type deviceState_ConnectivityEvent as ConnectivityEvent, type deviceState_ConnectivityIntent as ConnectivityIntent, type deviceState_ConnectivitySnapshot as ConnectivitySnapshot, type deviceState_DeviceBridgeDomain as DeviceBridgeDomain, deviceState_DeviceBridgeError as DeviceBridgeError, type deviceState_DeviceBridgeErrorCode as DeviceBridgeErrorCode, type deviceState_DeviceBridgeV2 as DeviceBridgeV2, type deviceState_DeviceContextDomain as DeviceContextDomain, type deviceState_DeviceContextSnapshot as DeviceContextSnapshot, type deviceState_DevicePlacement as DevicePlacement, type deviceState_DeviceState as DeviceState, type deviceState_DeviceToolContextV2Extension as DeviceToolContextV2Extension, type deviceState_EnvironmentDomain as EnvironmentDomain, type deviceState_EnvironmentEvent as EnvironmentEvent, type deviceState_EnvironmentIntent as EnvironmentIntent, type deviceState_EnvironmentSnapshot as EnvironmentSnapshot, type deviceState_Freshness as Freshness, type deviceState_FreshnessState as FreshnessState, type deviceState_HumanActivity as HumanActivity, type deviceState_InteractionDomain as InteractionDomain, type deviceState_InteractionEvent as InteractionEvent, type deviceState_InteractionSnapshot as InteractionSnapshot, type deviceState_MediaHandle as MediaHandle, type PermissionState$1 as PermissionState, type deviceState_PluginPropsV2Extension as PluginPropsV2Extension, type deviceState_RestrictionState as RestrictionState, type deviceState_SpatialDomain as SpatialDomain, type deviceState_SpatialEvent as SpatialEvent, type deviceState_SpatialIntent as SpatialIntent, type deviceState_SpatialPoint as SpatialPoint, type deviceState_SpatialSnapshot as SpatialSnapshot, type deviceState_SpatialStateEvent as SpatialStateEvent, type deviceState_StartOptions as StartOptions, type deviceState_StateDomainDeclaration as StateDomainDeclaration, type deviceState_StateEvent as StateEvent, type deviceState_StateListener as StateListener, type deviceState_StateQuality as StateQuality, type deviceState_StateSession as StateSession, type deviceState_StatefulDomain as StatefulDomain, type deviceState_Subscription as Subscription, type deviceState_SupportState as SupportState, type deviceState_VisualCaptureOptions as VisualCaptureOptions, type deviceState_VisualCaptureResult as VisualCaptureResult, type deviceState_VisualDomain as VisualDomain, type deviceState_VisualFrameQuality as VisualFrameQuality, type deviceState_VisualFrameRef as VisualFrameRef, type deviceState_VisualIntent as VisualIntent, type deviceState_VisualSnapshot as VisualSnapshot, deviceState_explainCapability as explainCapability, deviceState_isActionable as isActionable, deviceState_neverObserved as neverObserved };
 }
 
 /**
@@ -954,11 +1045,51 @@ 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 sessionId the Core allowset is bound to. Diagnostic: authorization
+     *  requires it to equal `sessionId`; a mismatch is why tools refuse. */
+    authorizedSessionId: string | null;
 }
 interface VoiceStartOptions {
     /** Hand the mic to a specific skill on connect (voice /session → takeMic),
      *  exactly as `sys.focusUiPlugin("platform:voice", { skillSlug })` does. */
     skillSlug?: string;
+    /**
+     * A PER-CALL persona override, same shape as the authored
+     * `solution.voice.persona` ({ name, style }). Declared on the voice
+     * session-create call (POST /session `persona`); the server sanitizes it
+     * (name/style only, length-capped) and layers it OVER the solution's authored
+     * persona for THIS call only — prompt-layer, so it can never touch caller
+     * verification or tool allow-lists. Set once at session start and constant
+     * for the call, so it adds no per-turn prompt pushes.
+     *
+     * Use it when a plugin needs its own voice persona without owning a skill
+     * (e.g. a guide HUD). A solution-wide persona belongs in solution.voice.
+     */
+    persona?: VoicePersona;
+    /**
+     * `'none'` = a CLEAN call: the voice gets none of the workspace's skills — no
+     * skill manifest, no skill tools, no platform welcome line, no mid-call
+     * skill-state prompt refresh — only the voice basics, this call's persona and
+     * the CALLING plugin's own device tools (other solutions' tools registered on
+     * the same phone are neither offered nor run). For a plugin that owns its conversation (e.g.
+     * a guide HUD). Reduce-only: it can remove what the voice gets, never add.
+     * Absent = the workspace's skills, as today. Not combinable with `skillSlug`.
+     */
+    skills?: 'none';
+}
+/** The authored persona shape (solution.voice.persona). */
+interface VoicePersona {
+    /** The name the voice uses for itself ("You are <name> …"). */
+    name?: string;
+    /** Free-text style/behaviour guidance rendered under the identity line. */
+    style?: string;
 }
 /**
  * What changed. Coarse on purpose: `state` covers connect/mute/session/partials,
@@ -1411,6 +1542,108 @@ interface VisionAPI {
     /** Measure whether a frame is usable. Feeds VisualFrameRef.quality. */
     assessQuality(frameId: string): Promise<VisionFrameQuality>;
 }
+/** The same `{ latitude, longitude }` `location.getCurrent` returns, so a fix
+ *  passes straight in. */
+interface MapsCoordinate {
+    latitude: number;
+    longitude: number;
+}
+/** A postal address, field by field. `null` = the map data has no value — never
+ *  an empty string, which would read as a street with no name. */
+interface MapsAddress {
+    /** The placemark's own name — a building, or often number + street. */
+    name: string | null;
+    street: string | null;
+    streetNumber: string | null;
+    /** Neighbourhood / sub-locality. */
+    district: string | null;
+    city: string | null;
+    /** State / province / administrative area. */
+    region: string | null;
+    postalCode: string | null;
+    country: string | null;
+    /** ISO 3166-1 alpha-2, e.g. "GB". */
+    isoCountryCode: string | null;
+}
+interface MapsPlace {
+    /** What the map calls it ("Boots", "10 Downing St"). Null when unnamed. */
+    name: string | null;
+    coordinate: MapsCoordinate;
+    address: MapsAddress;
+    /** Apple's point-of-interest category as a vocabulary term ("Pharmacy",
+     *  "Cafe", "PublicTransport") — NOT free text. Null for a plain address, or
+     *  when the service gives none. */
+    category: string | null;
+    /** Straight-line metres from `opts.near`, when you passed one — NOT walking
+     *  distance (ask `route` for that). Null without `near`. */
+    distanceM: number | null;
+}
+interface MapsRouteStep {
+    /** Apple's instruction ("Turn right onto Baker St"). The FIRST step is usually
+     *  an origin step with an empty instruction — kept, not dropped, so step
+     *  indexes line up with Apple's. */
+    instructions: string;
+    distanceM: number;
+    /** An advisory Apple attaches to this step. Null when there is none. */
+    notice: string | null;
+    polyline: MapsCoordinate[];
+}
+interface MapsRoute {
+    mode: 'walking';
+    distanceM: number;
+    /** Apple's estimate for the whole route. */
+    expectedTravelTimeMs: number;
+    steps: MapsRouteStep[];
+    /** The whole route, start to end. */
+    polyline: MapsCoordinate[];
+}
+interface MapsAPI {
+    /** Can this build search and route? True when the AdaMaps module is in the
+     *  binary (iOS). False on Android and on an older build — `reverseGeocode`
+     *  does not need the module and may still work there. */
+    isSupported(): Promise<boolean>;
+    /**
+     * Find places by free text — "pharmacy", "10 Downing Street".
+     *
+     * `near` centres the search on a coordinate YOU supply, within `radiusM`
+     * (default 3000, above 0 and at most 100 000). On iOS 18+ results are
+     * confined to that area; before 18 it is a strong hint and a farther result
+     * can come back — each result's `distanceM` says how far. At most `limit`
+     * results (default 8, from 1; more than 25 is capped at 25).
+     *
+     * Network, Apple's servers. `[]` = Apple looked and found nothing. iOS only:
+     * throws UNAVAILABLE on Android or a build without AdaMaps.
+     */
+    search(query: string, opts?: {
+        near?: MapsCoordinate;
+        radiusM?: number;
+        limit?: number;
+    }): Promise<MapsPlace[]>;
+    /**
+     * What is at a coordinate — its address and name.
+     *
+     * iOS AND Android (the platform geocoder); needs no AdaMaps module. The
+     * result's `coordinate` is the point you asked about, and its
+     * `category` / `distanceM` are null. `null` = nothing there.
+     *
+     * Network, not on-device. iOS reports a rate limit and a lost connection as
+     * the SAME error, so OFFLINE here can also mean "too many requests". Android's
+     * geocoder refuses without location permission (UNAVAILABLE) — that is the
+     * platform's rule, not a location read.
+     */
+    reverseGeocode(at: MapsCoordinate): Promise<MapsPlace | null>;
+    /**
+     * A walking route between two coordinates YOU supply.
+     *
+     * `null` = Apple found no route — never a fake 0 m route, which would read as
+     * "you have arrived". Walking is the only mode; any other refuses by name.
+     * Network, Apple's servers. iOS only: throws UNAVAILABLE on Android or a build
+     * without AdaMaps.
+     */
+    route(from: MapsCoordinate, to: MapsCoordinate, opts?: {
+        mode?: 'walking';
+    }): Promise<MapsRoute | null>;
+}
 interface BluetoothAPI {
     /** Is BLE hardware present and permitted? */
     isSupported(): Promise<boolean>;
@@ -1481,6 +1714,9 @@ interface PluginNative {
     bluetooth: BluetoothAPI;
     /** SHAPE ONLY in this build — see VisionAPI. On-device image understanding. */
     vision: VisionAPI;
+    /** Place search, reverse geocoding, walking routes — see MapsAPI. Sends
+     *  queries to Apple's map servers; NOT on-device. */
+    maps: MapsAPI;
 }
 interface NativeCapabilities$1 {
     camera?: boolean;
@@ -1496,6 +1732,9 @@ interface NativeCapabilities$1 {
     /** On-device image understanding (OCR, labels, frame quality). Refuses by
      *  name until the native module lands — see VisionAPI. */
     vision?: boolean;
+    /** Place search, reverse geocoding, walking routes. Means "may send place
+     *  queries to Apple Maps" — network, not on-device. See MapsAPI. */
+    maps?: boolean;
     /** The live voice SESSION (props.voice). A privacy surface — a declaring
      *  plugin can read the conversation transcript — so it is gated like any
      *  other capability, and coupled to the platform's unsuppressable mic
@@ -1649,8 +1888,9 @@ interface PluginManifest$1 {
     };
     capabilities?: Record<string, unknown>;
     /** L3 DeviceState domains this plugin reads (props.deviceState), as Core passes
-     *  them through from the bundle's declaration. Absent → fall back to the loaded
-     *  bundle's own `stateDomains`. Read via resolvePluginRuntimeProps. */
+     *  them through from the solution's declaration. Absent → NO domains (fail
+     *  closed): the loaded bundle's own `stateDomains` is never consulted when a
+     *  manifest exists. Read via resolvePluginRuntimeProps. */
     stateDomains?: DeviceBridgeDomain[];
     _source?: string;
     _connectorId?: string;
@@ -1688,6 +1928,9 @@ interface DeviceToolContext {
      * the same gating a UI plugin's `props.deviceState` gets. This is what lets an
      * EXTERNAL tool (e.g. Ada Guide's `guide.observe`) read `ctx.deviceState.visual`
      * over the public surface, with no SDK-internal access.
+     *
+     * `subscribe` refuses (RESTRICTED) on every domain: a call has no lifetime to
+     * own a subscription, and the engines outlive it. Read instead.
      */
     deviceState: DeviceState;
     /** Cooperative cancellation: caller cancelled, or the session went away. */
@@ -1708,9 +1951,10 @@ interface RegisteredToolsPlugin {
     type: 'tools';
     capabilities?: NativeCapabilities$1;
     /**
-     * L3 DeviceState domains this plugin's tools may read via `ctx.deviceState`
-     * (e.g. `['visual']`). Undeclared domains answer "not declared". Same
-     * mechanism as a UI plugin's manifest `stateDomains`.
+     * L3 DeviceState domains this plugin's tools read via `ctx.deviceState` (e.g.
+     * `['visual']`). For a remote bundle this is the author's statement, not a
+     * grant: the tools get the manifest's `stateDomains` (resolvePluginGrants),
+     * and a domain declared here but not there is denied with a warning.
      */
     stateDomains?: DeviceBridgeDomain[];
     tools: DeviceToolDefinition[];
@@ -1748,7 +1992,8 @@ declare function register(id: string, config: {
  */
 declare function registerTools(id: string, config: {
     capabilities?: NativeCapabilities$1;
-    /** L3 DeviceState domains the tools may read via ctx.deviceState (e.g. ['visual']). */
+    /** L3 DeviceState domains the tools read via ctx.deviceState (e.g. ['visual']).
+     *  For a remote bundle the MANIFEST grants them — see RegisteredToolsPlugin. */
     stateDomains?: DeviceBridgeDomain[];
     tools: DeviceToolDefinition[];
 }): RegisteredToolsPlugin;
@@ -2006,11 +2251,6 @@ interface PluginRuntimeProps {
     deviceState: DeviceState;
     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$1 | Record<string, unknown>;
@@ -2033,9 +2273,17 @@ interface PluginRuntimeSource {
      */
     plugin?: PluginDeclaration | null;
 }
+/** 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). */
+interface PluginGrants {
+    capabilities?: NativeCapabilities$1;
+    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
@@ -2045,6 +2293,9 @@ interface PluginRuntimeSource {
  * not carry `stateDomains` for a remote plugin, the fix is Core passing it, not
  * trusting the bundle: Core already holds the solution's declaration.)
  */
+declare function resolvePluginGrants(src: PluginRuntimeSource): PluginGrants;
+/** Turn a plugin's grants into the gated { device, native, deviceState, voice } it
+ *  receives on every rendered surface. */
 declare function resolvePluginRuntimeProps(src: PluginRuntimeSource): PluginRuntimeProps;
 
 interface DeviceToolSummary {
@@ -2077,7 +2328,9 @@ declare function setDeviceToolContextProvider(fn: (pluginId: string, capabilitie
 declare function registerDeviceTools(pluginId: string, tools: DeviceToolDefinition[], capabilities?: NativeCapabilities$1, stateDomains?: DeviceBridgeDomain[]): string[];
 /** Drop every tool owned by a plugin (bundle eviction / plugin revoked). */
 declare function unregisterDeviceTools(pluginId: string): void;
-declare function hasDeviceTool(name: string): boolean;
+/** Is `name` registered — and, given `pluginId`, registered BY that plugin?
+ *  (A clean voice call only lets its owner's own tools run.) */
+declare function hasDeviceTool(name: string, pluginId?: string): boolean;
 declare function listDeviceTools(): DeviceToolSummary[];
 /**
  * Invoke a device tool. Never throws — every failure comes back as a typed
@@ -2210,6 +2463,9 @@ declare class BundleManager {
      * of the previous tenant's tools.
      */
     private registeredToolPluginIds;
+    /** 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;
     /**
      * Enforce the in-memory tenant boundary. Call at the top of every public load
      * path, BEFORE any cache read.
@@ -2237,9 +2493,11 @@ declare class BundleManager {
      *  tenant switch (or wipe) happened while this load was in flight. Its results
      *  belong to a tenant that is no longer current and must be discarded. */
     private isStale;
-    /** 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. */
+    /** 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;
     /**
      * Load a plugin component. Returns the RegisteredUIPlugin object.
@@ -2249,16 +2507,26 @@ declare 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.
      */
-    load(pluginId: string, bundleUrl: string, version: string, expectedHash?: string): Promise<RegisteredUIPlugin>;
+    load(pluginId: string, bundleUrl: string, version: string, expectedHash?: string, grants?: PluginGrants): Promise<RegisteredUIPlugin>;
     /**
      * Load a bundle for its `tools/` section only — no UI required.
      *
      * 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.
      */
-    loadTools(pluginId: string, bundleUrl: string, version: string, expectedHash?: string): Promise<string[]>;
+    loadTools(pluginId: string, bundleUrl: string, version: string, expectedHash: string | undefined, grants: PluginGrants): Promise<string[]>;
     /**
      * Prewarm: load every plugin bundle in the background after app boot, so a
      * later open is instant (in-memory hit) instead of round-tripping the
@@ -2270,6 +2538,8 @@ declare class BundleManager {
         bundleUrl: string;
         version: string;
         bundleHash?: string;
+        /** The manifest's grants, when the caller has the manifest (see load()). */
+        grants?: PluginGrants;
     }>): Promise<void>;
     /**
      * Clear all caches (in-memory + storage).
@@ -2290,11 +2560,36 @@ declare class BundleManager {
     getLoadedBundles(): LoadedBundleInfo[];
     private loadModule;
     /**
-     * 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.
+     * 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 commitTools;
+    /**
+     * 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;
+    /**
+     * 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 recordTrustedDeclaration;
     /**
      * Download + integrity-verify a bundle. Refuses to return when:
      *   - manifest hash and computed hash disagree
@@ -2304,11 +2599,15 @@ declare class BundleManager {
      */
     private download;
     private evaluate;
+    /** Find a plugin component in a loaded module. */
+    private getComponentFromMemory;
     /**
-     * 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;
+    private findPluginExport;
     private describeModule;
 }
 /** Singleton — shared across all plugin renderers */
@@ -2321,6 +2620,7 @@ declare const bundleManager: BundleManager;
  * default is in-memory (bundles re-download per app session — correct,
  * just slower on cold start).
  */
+
 interface BundleCacheEntry {
     localPath: string;
     version: string;
@@ -2342,6 +2642,23 @@ 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. */
+interface TrustedToolDeclaration extends PluginGrants {
+    pluginId: string;
 }
 interface BundleStorage {
     loadIndex(): Promise<Record<string, BundleCacheEntry>>;
@@ -2572,6 +2889,9 @@ interface PluginManifestLike {
     name?: string;
     render?: any;
     _connectorId?: string;
+    capabilities?: Record<string, unknown>;
+    native?: NativeCapabilities$1;
+    stateDomains?: DeviceBridgeDomain[];
 }
 interface UsePluginResult {
     plugin: RegisteredUIPlugin | null;
@@ -2890,4 +3210,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, MemoryBundleStorage, type MountSurfaceManifest, type NativeCapabilities$1 as NativeCapabilities, type NfcAPI, type NotificationsAPI, PLATFORM_VOICE_CALLER, type PluginManifest as PlatformPluginManifest, type PluginBridge, type PluginContext, 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 SpatialIntent, type SpatialPoint, type SpatialSnapshot, type StateQuality, type StorageAPI, SurfaceCard, type SurfaceCardProps, SurfaceDispatcher, SurfaceDrawer, type SurfaceDrawerProps, SurfaceFullscreen, type SurfaceFullscreenProps, type SurfaceManifest, type SurfacePlacement, type SurfaceType, type SurfaceVisibility, TabBar, type ThemeTokens, type VisionAPI, type VisionFrameQuality, type VisionLabel, type VisionObject, type VisionText, type VisualSnapshot, type VoiceAPI, type VoiceCaller, type VoiceEvent, 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, 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 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 };