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

package/src/sdk/types.ts

@@ -352,6 +352,139 @@ export interface VisionAPI {
   assessQuality(frameId: string): Promise<VisionFrameQuality>;
 }
 
+// ── Maps — where is X, what is here, how do I walk there ──
+//
+// One-shot verbs that THROW, like vision — not a state domain. Following a
+// route over time (progress, off-route, "turn left in 20 m") is the reasoning
+// loop's job over deviceState.spatial; this layer answers each question once.
+//
+// NOT ON-DEVICE — the opposite of vision, and the thing not to get wrong when
+// describing a feature built on it. Every call sends the query and the
+// coordinates you pass to a map service over the network: Apple's (MapKit /
+// CLGeocoder) on iOS, the platform geocoder on Android. So the `maps` flag
+// means exactly one thing: "this plugin may send place queries to Apple Maps".
+//
+// IT NEVER READS THE USER'S LOCATION. Every coordinate is the caller's — take a
+// fix from `location.getCurrent` or `deviceState.spatial` and pass it in. That
+// keeps `maps` from becoming a second, differently-gated door to where the
+// user is.
+//
+// FOUND NOTHING IS AN ANSWER; COULD NOT LOOK THROWS. `[]` / `null` mean the
+// service looked and there is nothing. Anything else THROWS, with a code:
+//   UNAVAILABLE  this app build has no AdaMaps module (needs a native rebuild),
+//                or the platform has none — search/route are iOS only (MapKit)
+//                and refuse by name on Android. Also the service's own failures.
+//   OFFLINE      the map service could not be reached.
+//   THROTTLED    Apple is rate-limiting this app. A burst of queries is what
+//                trips it — search once per intent, not once per frame.
+// And one refusal that is not a failure to look:
+//   INVALID_ARGUMENT  the call itself is malformed — an empty query, a
+//                coordinate that is not { latitude, longitude } finite numbers in
+//                range (`{ lat, lng }` refuses), a limit or radius out of range.
+//                Nothing was sent; fix the call rather than retrying it.
+
+/** The same `{ latitude, longitude }` `location.getCurrent` returns, so a fix
+ *  passes straight in. */
+export 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. */
+export 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;
+}
+
+export 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;
+}
+
+export 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[];
+}
+
+export 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[];
+}
+
+export 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>;
+}
+
 export interface BluetoothAPI {
   /** Is BLE hardware present and permitted? */
   isSupported(): Promise<boolean>;
@@ -420,6 +553,9 @@ export 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;
 }
 
 // ── Native capability flags (manifest declaration) ──────────
@@ -438,6 +574,9 @@ export interface NativeCapabilities {
   /** 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
@@ -570,8 +709,9 @@ export interface PluginManifest {
   channels?: string[] | { events: string[]; actions: string[] };
   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;
@@ -616,6 +756,9 @@ export 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. */
@@ -624,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;
@@ -639,9 +795,10 @@ export interface RegisteredToolsPlugin {
   type: 'tools';
   capabilities?: NativeCapabilities;
   /**
-   * 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[];

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,12 +88,58 @@ 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 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;
 }
 
 export 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). */
+export 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;
 }
 
 /**

package/src/tools/loader.ts

@@ -13,7 +13,8 @@
 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';
 
 let inflight: Promise<string[]> | null = null;
@@ -54,9 +55,9 @@ export async function ensureDeviceToolsLoaded({ force = false } = {}): Promise<s
         // a fact about a server process, not about this phone — the bundle we
         // already downloaded still has the tools in it.
         //
-        // So fall back to what is on disk. Re-evaluating a cached bundle
-        // re-registers whatever it declares, and a bundle with no tools is a
-        // no-op, so this is safe to do blind.
+        // So fall back to what is on disk: re-evaluate this tenant's cached
+        // bundles under the trusted declaration recorded when a manifest last
+        // loaded them (see loadFromDiskCache).
         const recovered = await loadFromDiskCache();
         if (recovered.length > 0) {
           console.log(`[deviceTools] catalog listed none — recovered from cache: ${recovered.join(', ')}`);
@@ -75,11 +76,14 @@ export async function ensureDeviceToolsLoaded({ force = false } = {}): Promise<s
             return;
           }
           try {
+            // The manifest is the authority on what the tools may touch — the
+            // same grants its rendered surface gets, never the bundle's claim.
             await bundleManager.loadTools(
               m.id,
               bundleUrl,
               m.version || '1.0.0',
               getNativeBundleHash(m) || undefined,
+              resolvePluginGrants({ pluginId: m.id, manifest: m }),
             );
           } catch (err: any) {
             console.warn(`[deviceTools] ${m.id} failed to load:`, err?.message || String(err));
@@ -127,10 +131,20 @@ export async function ensureDeviceToolsLoaded({ force = false } = {}): Promise<s
  * An entry with no recorded tenant predates the stamp. Its owner is unknown,
  * which means untrusted — skip it and let the normal catalog path re-download
  * it under a real hash gate.
+ *
+ * GRANTS COME FROM THE RECORDED MANIFEST, NEVER THE BUNDLE. With no manifest
+ * here, the tools register under the `trusted` declaration (pluginId +
+ * capabilities + stateDomains) the bundle manager recorded on the entry when a
+ * manifest last loaded these bytes. An entry without one — written before the
+ * record existed, or never loaded under a manifest — is skipped (fail closed):
+ * the only other source is the bundle's own claim, and the catalog path
+ * registers it properly once its connector answers.
  */
 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 [];
 
@@ -145,11 +159,17 @@ async function loadFromDiskCache(): Promise<string[]> {
     if (skipped > 0) {
       console.log(`[deviceTools] disk-cache recovery: ${mine.length} for "${tenant}", skipped ${skipped} not owned by it`);
     }
-    if (mine.length === 0) return [];
+    const declared = mine.filter((e) => !!e.trusted?.pluginId);
+    if (declared.length < mine.length) {
+      console.log(
+        `[deviceTools] disk-cache recovery: skipped ${mine.length - declared.length} with no recorded manifest grant (fail closed)`,
+      );
+    }
+    if (declared.length === 0) return [];
 
-    await Promise.all(mine.map(async (e: any) => {
+    await Promise.all(declared.map(async (e) => {
       try {
-        await bundleManager.loadTools('cache:' + e.bundleUrl, e.bundleUrl, e.version, e.bundleHash);
+        await bundleManager.loadTools(e.trusted!.pluginId, e.bundleUrl, e.version, e.bundleHash, e.trusted!);
       } catch {
         // A cached bundle that no longer loads is not worth failing a call over.
       }

package/src/tools/registry.ts

@@ -14,8 +14,8 @@
  */
 import { createNativeBridge } from '../bridge/native';
 import { getPluginNative, gatePluginNative } from '../host';
-import { gateDeviceState } from '../deviceStateHost';
-import type { DeviceToolContext, DeviceToolDefinition, NativeCapabilities } from '../sdk/types';
+import { gateDeviceState, withoutSubscribe } from '../deviceStateHost';
+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;
@@ -62,7 +62,8 @@ export function setDeviceToolContextProvider(
  * Default context: the plugin's own bridge + a capability-gated Device Bridge +
  * the L3 DeviceState gated to the domains the plugin declared. All three are the
  * SAME gated objects the plugin gets when it renders — a tool reaches nothing a
- * UI plugin couldn't.
+ * UI plugin couldn't. (One thing less: `callDeviceTool` takes `subscribe` away,
+ * because a call has no lifetime to own one.)
  */
 function defaultContext(
   pluginId: string,
@@ -120,8 +121,11 @@ export function unregisterDeviceTools(pluginId: string): void {
   }
 }
 
-export function hasDeviceTool(name: string): boolean {
-  return registry.has(name);
+/** Is `name` registered — and, given `pluginId`, registered BY that plugin?
+ *  (A clean voice call only lets its owner's own tools run.) */
+export function hasDeviceTool(name: string, pluginId?: string): boolean {
+  const entry = registry.get(name);
+  return !!entry && (pluginId === undefined || entry.pluginId === pluginId);
 }
 
 export function listDeviceTools(): DeviceToolSummary[] {
@@ -152,8 +156,11 @@ export async function callDeviceTool(
 
   try {
     const build = contextProvider || defaultContext;
+    const built = build(entry.pluginId, entry.capabilities, entry.stateDomains);
     const ctx: DeviceToolContext = {
-      ...build(entry.pluginId, entry.capabilities, entry.stateDomains),
+      ...built,
+      // Whoever built the context, a call cannot own a subscription.
+      deviceState: withoutSubscribe(built.deviceState),
       signal: opts.signal,
     };
 

package/src/voiceHost.ts

@@ -62,6 +62,8 @@ function deniedVoice(why: string): VoiceAPI {
         listening: false,
         userSpeaking: false,
         lastUserSpeechEndedAt: null,
+        lastDeviceTool: null,
+        authorizedSessionId: null,
         lastError: why,
       };
     },