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

package/src/sdk/voice.ts

@@ -0,0 +1,186 @@
+/**
+ * props.voice — the live conversational SESSION a plugin may drive.
+ *
+ * Voice is a SESSION, not a device sensor. `props.device.*` is mechanical verbs
+ * that throw; `props.deviceState.*` is eight semantic domains describing the
+ * device. A Realtime conversation is neither — it is a long-lived loop with its
+ * own state (connecting/connected), its own transcript, and two ways to take a
+ * turn (the user speaks, or the agent speaks first). So it gets its own gated
+ * surface, mirroring the deviceState GRAMMAR (start / stop / getSnapshot /
+ * subscribe) because a reasoning loop reads it the same way — state with
+ * freshness, not bare values.
+ *
+ * TRUST BOUNDARY. This type is the WHOLE surface. There is deliberately NO way
+ * from here to inject fake user speech, read raw audio, reach the WebView, or
+ * hide the mic-active indicator — those are new doors, and the reason
+ * `CameraPreview` is a component rather than a module is that we keep closing
+ * doors of that shape. `prompt()` is an AGENT turn, not a forged user turn.
+ *
+ * See docs/handoff/SPEC_voice_session_without_the_voice_screen_2026-09-12.md.
+ */
+
+/** The session lifecycle — identical vocabulary to the built-in `CallState`. */
+export type VoiceState = 'idle' | 'connecting' | 'connected' | 'error';
+
+/** One line of the conversation. `tool` entries are device/skill tool activity. */
+export interface VoiceTranscriptEntry {
+  role: 'user' | 'ai' | 'tool';
+  text: string;
+  ts: number;
+}
+
+/** A point-in-time read of the session — what a reasoning loop polls. */
+export interface VoiceSnapshot {
+  state: VoiceState;
+  sessionId: string | null;
+  muted: boolean;
+  /** The agent is currently producing audio. */
+  speaking: boolean;
+  /** The user is currently being heard (partial user transcript in flight). */
+  listening: boolean;
+  /** The user is currently speaking, per the session's own VAD (authoritative,
+   *  distinct from `listening` which tracks a partial transcript). */
+  userSpeaking: boolean;
+  /**
+   * Epoch ms of the last moment the user STOPPED speaking, or `null` if they
+   * have not spoken yet this session. `null` is deliberate and load-bearing: a
+   * silence timer must arm on the first real `speaking:false`, never at session
+   * start — "not speaking" and "has never spoken" are different, and arming on
+   * the wrong one fires before anyone has said anything.
+   */
+  lastUserSpeechEndedAt: number | null;
+  /** 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;
+}
+
+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;
+}
+
+/**
+ * What changed. Coarse on purpose: `state` covers connect/mute/session/partials,
+ * `transcript` fires when a finalized line was appended. A subscriber re-reads
+ * `getSnapshot()` / `transcript()` — the event is a nudge, not a payload, so the
+ * surface never has to keep two shapes of the same fact in sync.
+ */
+export type VoiceEvent = { type: 'state' } | { type: 'transcript' };
+
+export interface VoiceSubscription {
+  unsubscribe(): void;
+}
+
+/**
+ * WHO is asking. The one physical session has an OWNER; access is scoped to it.
+ *
+ * A plugin's caller is its `pluginId` (a string), stamped by gateVoice so the
+ * plugin never supplies its own identity. The PLATFORM caller — the built-in
+ * voice screen, the user's own surface — is a Symbol, deliberately: a Symbol can
+ * never equal any pluginId string, so a plugin cannot forge platform access by
+ * naming itself `platform:voice`.
+ */
+export type VoiceCaller = string | symbol;
+
+/** The privileged caller — the platform's own surfaces (the built-in sheet, the
+ *  mic indicator, the session host). Sees and controls any live session, because
+ *  it is the USER's direct surface onto their own conversation. Unforgeable. */
+export const PLATFORM_VOICE_CALLER: unique symbol = Symbol('adas.voice.platform');
+
+/**
+ * The OWNER-AWARE session the HOST implements and hands to setVoiceProvider.
+ *
+ * This is NOT what a plugin receives — a plugin gets a `VoiceAPI` facade
+ * (gateVoice) that stamps its `pluginId` as the caller on every call, so the
+ * provider can enforce that a plugin only ever reads, controls, or attaches to a
+ * session IT owns. One physical session, isolated per authorized identity.
+ */
+export interface VoiceSessionProvider {
+  start(opts: VoiceStartOptions | undefined, caller: VoiceCaller): Promise<VoiceSnapshot>;
+  stop(caller: VoiceCaller): void;
+  setMuted(muted: boolean, caller: VoiceCaller): void;
+  prompt(input: string, caller: VoiceCaller): void;
+  observe(text: string, caller: VoiceCaller): void;
+  getSnapshot(caller: VoiceCaller): VoiceSnapshot;
+  subscribe(cb: (event: VoiceEvent) => void, caller: VoiceCaller): VoiceSubscription;
+  transcript(caller: VoiceCaller): VoiceTranscriptEntry[];
+}
+
+/**
+ * The gated surface a plugin receives as `props.voice`. Present on EVERY plugin;
+ * a plugin that did not declare `capabilities: { voice: true }` gets a version
+ * whose reads say so and whose actions throw — never a silent no-op, never a
+ * fake `idle` (see gateVoice in voiceHost.ts).
+ */
+export interface VoiceAPI {
+  /** Open the live loop. Resolves once connected (or rejects on connect error).
+   *  If a session is ALREADY live, ATTACHES to it and resolves immediately —
+   *  never a second Realtime loop (one phone, one mic, one bill). */
+  start(opts?: VoiceStartOptions): Promise<VoiceSnapshot>;
+  /** End the live loop. Safe to call when idle. */
+  stop(): void;
+  /** Mute/unmute the microphone. The session stays live; the mic indicator
+   *  reflects it. */
+  setMuted(muted: boolean): void;
+  /**
+   * Make the agent take a turn WITHOUT the user speaking — the guide speaking
+   * first. `input` is the instruction for that turn. This is an agent-initiated
+   * turn into the SAME session, NOT fabricated user speech: one session, two
+   * trigger sources. Throws if the session is not connected.
+   */
+  prompt(input: string): void;
+  /**
+   * Stream a silent OBSERVATION into the session — tell the model something
+   * without asking it to speak (a `system` conversation item). Cheap and
+   * high-frequency (safe once or twice a second): this is the channel for what
+   * the camera sees while the user walks. The model answers with the
+   * observations in hand the next time it takes a turn (user VAD, or prompt()) —
+   * an observation never triggers a turn by itself. Throws if not connected.
+   */
+  observe(text: string): void;
+  /** Point-in-time session state. */
+  getSnapshot(): VoiceSnapshot;
+  /** Subscribe to state + transcript changes. Returns an unsubscribe handle. */
+  subscribe(cb: (event: VoiceEvent) => void): VoiceSubscription;
+  /** The conversation so far. */
+  transcript(): VoiceTranscriptEntry[];
+}

package/src/tools/loader.ts

@@ -0,0 +1,185 @@
+/**
+ * Device tool loading.
+ *
+ * A device tool is only callable once its plugin bundle has been evaluated —
+ * that is when the tools register (see `./registry`). Nothing else in the app
+ * guarantees that: bundle prewarm runs on the home screen and is best-effort, so
+ * a user who goes straight into a voice call can reach a tool the phone has
+ * never loaded. The model then hears "no such tool" and improvises, which looks
+ * exactly like a broken feature.
+ *
+ * So the voice path calls `ensureDeviceToolsLoaded()` before connecting.
+ */
+import { listPlugins, getPlugin, getNativeBundleUrl, getNativeBundleHash } from '../api/plugins';
+import { bundleManager } from '../bundles/bundleManager';
+import { listDeviceTools } from './registry';
+import { getBundleStorage, selectOwnedCacheEntries } from '../bundles/storage';
+import { resolvePluginGrants } from '../pluginRuntime';
+import { getTenant } from '@ateam-ai-mobile/core';
+
+let inflight: Promise<string[]> | null = null;
+let loadedOnce = false;
+
+/**
+ * Load every plugin that declares `capabilities.device_tools`, so its tools are
+ * registered and callable. Best-effort and idempotent: safe to call on every
+ * call start. Returns the tool names currently registered.
+ *
+ * Pass `force` after a plugin catalog change (a newly deployed connector).
+ */
+export async function ensureDeviceToolsLoaded({ force = false } = {}): Promise<string[]> {
+  if (loadedOnce && !force) return listDeviceTools().map(t => t.name);
+  if (inflight) return inflight;
+
+  inflight = (async () => {
+    try {
+      const summaries = await listPlugins();
+
+      // The list response is slim, so the manifest is the authority on whether a
+      // plugin declares device tools. Fetched in parallel — a cold connector
+      // that answers slowly must not hold up a call.
+      const manifests = await Promise.all(
+        (summaries || []).map(s =>
+          getPlugin((s as any).id).catch(() => null),
+        ),
+      );
+
+      const targets = manifests.filter((m: any) => {
+        const declared = m?.capabilities?.device_tools;
+        return Array.isArray(declared) && declared.length > 0;
+      });
+
+      if (targets.length === 0) {
+        // The catalog can go blind: a solution connector is lazy, and while it
+        // is not running its plugins are absent from the list entirely. That is
+        // 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-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(', ')}`);
+          return recovered;
+        }
+        // Do NOT latch: "nothing yet" is usually just "not yet".
+        console.log('[deviceTools] no device tools available yet — will look again next call');
+        return [];
+      }
+
+      await Promise.all(
+        targets.map(async (m: any) => {
+          const bundleUrl = getNativeBundleUrl(m);
+          if (!bundleUrl) {
+            console.warn(`[deviceTools] ${m.id} declares device_tools but has no native bundle`);
+            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));
+          }
+        }),
+      );
+
+      const names = listDeviceTools().map(t => t.name);
+      // Only latch on success. An empty result is a cold read, not a fact —
+      // same reasoning as the server-side discovery cache.
+      loadedOnce = names.length > 0;
+      console.log(`[deviceTools] ready: ${names.length > 0 ? names.join(', ') : '(none registered — will retry next call)'}`);
+      return names;
+    } finally {
+      inflight = null;
+    }
+  })();
+
+  return inflight;
+}
+
+/**
+ * Re-evaluate the CURRENT TENANT'S bundles already cached on disk.
+ *
+ * Used when the plugin catalog comes back empty — which happens whenever the
+ * owning connector is asleep. This is a local read, not a download.
+ *
+ * TENANT SCOPING IS LOAD-BEARING, NOT DEFENCE IN DEPTH.
+ *
+ * Every other load path is gated by the manifest hash: the expected hash comes
+ * from the current tenant's server, so another tenant's cached bytes simply
+ * fail to match and are re-downloaded. This path has no manifest — that is the
+ * whole reason it exists — so it passes each entry's OWN stored hash as the
+ * expected hash. That check compares an entry to itself and can never fail. It
+ * is an integrity check against disk corruption, and it is not, and cannot be,
+ * an authorisation check.
+ *
+ * Without the tenant filter below this loop re-evaluated EVERY cached bundle,
+ * so a plugin cached during a session on tenant A registered its device tools
+ * into a live session on tenant B, and subsequent tool calls ran tenant-A code
+ * holding tenant-B credentials. No id collision was required: bundle urls are
+ * identical across tenants and resolve per-tenant on the server, and the code
+ * cache deliberately survives logout.
+ *
+ * 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();
+    const entries = Object.values(index || {});
+    if (entries.length === 0) return [];
+
+    const tenant = getTenant();
+    if (!tenant) {
+      // No active tenant: nothing can be proven to be ours.
+      console.warn('[deviceTools] disk-cache recovery skipped — no active tenant');
+      return [];
+    }
+    const mine = selectOwnedCacheEntries(entries, tenant);
+    const skipped = entries.length - mine.length;
+    if (skipped > 0) {
+      console.log(`[deviceTools] disk-cache recovery: ${mine.length} for "${tenant}", skipped ${skipped} not owned by it`);
+    }
+    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(declared.map(async (e) => {
+      try {
+        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.
+      }
+    }));
+    return listDeviceTools().map(t => t.name);
+  } catch (err: any) {
+    console.warn('[deviceTools] disk-cache recovery failed:', err?.message || String(err));
+    return [];
+  }
+}
+
+/** Forget that we loaded, so the next call re-reads the catalog. */
+export function resetDeviceToolLoader(): void {
+  loadedOnce = false;
+}

package/src/tools/platformTools.ts

@@ -0,0 +1,41 @@
+/**
+ * Platform device tools.
+ *
+ * These are not a solution's plugin tools — they ship with the SDK and every
+ * host has them, which is what makes a device tool testable without deploying
+ * anything to a tenant. Their names and contracts are declared once on the
+ * server (connectors/platform/device-tools-mcp.json); this is the device half.
+ *
+ * Registered at import, so a client answers them even before any plugin bundle
+ * has loaded — that is the point: proving the device path works should not
+ * depend on the thing being proved.
+ */
+import { registerDeviceTools } from './registry';
+
+const PLATFORM_PLUGIN_ID = 'platform:device-tools';
+
+export function registerPlatformDeviceTools(): void {
+  registerDeviceTools(PLATFORM_PLUGIN_ID, [
+    {
+      name: 'device.echo',
+      description: "Echo a string back from the user's own device.",
+      input_schema: {
+        type: 'object',
+        properties: { text: { type: 'string' } },
+        required: ['text'],
+      },
+      run: (args: any) => ({
+        ok: true,
+        echoed: (args && args.text) || '',
+        // The proof: a server-side implementation could not say this truthfully.
+        ran_on: 'device',
+      }),
+    },
+    {
+      name: 'device.ping',
+      description: 'Check that the device is reachable.',
+      input_schema: { type: 'object', properties: {} },
+      run: () => ({ ok: true, ran_on: 'device', at: new Date().toISOString() }),
+    },
+  ]);
+}

package/src/tools/registry.ts

@@ -0,0 +1,190 @@
+/**
+ * Device tool registry.
+ *
+ * A solution's RN plugin may ship a `tools/` section alongside (or instead of)
+ * its UI. Those tools are registered HERE, when the bundle is evaluated — not
+ * when a screen mounts — so a caller can invoke one with nothing of the plugin
+ * on screen.
+ *
+ * Lookup is by the tool's own domain name (e.g. "guide.observe"). Callers never
+ * route on a name prefix: whether a tool runs locally is declared by the server
+ * in the session payload, and resolved against this registry. The full LOCAL
+ * reasoning path (discovery → call → result, and its independence from
+ * relay/MCP) is documented in docs/architecture/LOCAL_REASONING_PATH.md (R13).
+ */
+import { createNativeBridge } from '../bridge/native';
+import { getPluginNative, gatePluginNative } from '../host';
+import { gateDeviceState, withoutSubscribe } from '../deviceStateHost';
+import type { DeviceToolContext, DeviceToolDefinition, NativeCapabilities } from '../sdk/types';
+import type { DeviceBridgeDomain } from '../sdk/device-state';
+
+export interface DeviceToolSummary {
+  name: string;
+  pluginId: string;
+  description?: string;
+  input_schema?: Record<string, unknown>;
+}
+
+export type DeviceToolOutcome =
+  | { ok: true; result: any }
+  | { ok: false; error: string; reason: 'not_found' | 'no_context' | 'timeout' | 'failed' };
+
+interface Entry {
+  pluginId: string;
+  tool: DeviceToolDefinition;
+  capabilities?: NativeCapabilities;
+  /** L3 DeviceState domains this plugin declared — gates ctx.deviceState. */
+  stateDomains?: DeviceBridgeDomain[];
+}
+
+/** toolName → entry. One name, one implementation. */
+const registry = new Map<string, Entry>();
+
+/** Optional host override; the SDK supplies a working default (see below). */
+let contextProvider:
+  | ((pluginId: string, capabilities?: NativeCapabilities, stateDomains?: DeviceBridgeDomain[]) => DeviceToolContext)
+  | null = null;
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Override how a device tool reaches the Device Bridge. Rarely needed — the
+ * default below builds the same bridge/native pair a plugin gets when it
+ * renders, gated by the capabilities the plugin declared.
+ */
+export function setDeviceToolContextProvider(
+  fn: (pluginId: string, capabilities?: NativeCapabilities, stateDomains?: DeviceBridgeDomain[]) => DeviceToolContext,
+): void {
+  contextProvider = fn;
+}
+
+/**
+ * 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. (One thing less: `callDeviceTool` takes `subscribe` away,
+ * because a call has no lifetime to own one.)
+ */
+function defaultContext(
+  pluginId: string,
+  capabilities?: NativeCapabilities,
+  stateDomains?: DeviceBridgeDomain[],
+): DeviceToolContext {
+  return {
+    bridge: createNativeBridge(pluginId),
+    native: gatePluginNative(getPluginNative(), capabilities, pluginId),
+    deviceState: gateDeviceState(stateDomains),
+  };
+}
+
+/**
+ * Register a plugin's tools. Called from the bundle pipeline at load time.
+ *
+ * A name already taken by ANOTHER plugin is refused — a bundle loaded later
+ * must not be able to take over "guide.observe" from the plugin that owns it.
+ * Re-registering the same plugin (bundle reload) replaces its own entries.
+ */
+export function registerDeviceTools(
+  pluginId: string,
+  tools: DeviceToolDefinition[],
+  capabilities?: NativeCapabilities,
+  stateDomains?: DeviceBridgeDomain[],
+): string[] {
+  const accepted: string[] = [];
+
+  for (const tool of tools || []) {
+    if (!tool || typeof tool.name !== 'string' || typeof tool.run !== 'function') {
+      console.warn(`[deviceTools] ${pluginId}: skipping malformed tool entry`);
+      continue;
+    }
+    const existing = registry.get(tool.name);
+    if (existing && existing.pluginId !== pluginId) {
+      console.warn(
+        `[deviceTools] ${pluginId}: "${tool.name}" already registered by ${existing.pluginId} — refusing to override`,
+      );
+      continue;
+    }
+    registry.set(tool.name, { pluginId, tool, capabilities, stateDomains });
+    accepted.push(tool.name);
+  }
+
+  if (accepted.length > 0) {
+    console.log(`[deviceTools] ${pluginId} registered: ${accepted.join(', ')}`);
+  }
+  return accepted;
+}
+
+/** Drop every tool owned by a plugin (bundle eviction / plugin revoked). */
+export function unregisterDeviceTools(pluginId: string): void {
+  for (const [name, entry] of registry.entries()) {
+    if (entry.pluginId === pluginId) registry.delete(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[] {
+  return Array.from(registry.entries()).map(([name, { pluginId, tool }]) => ({
+    name,
+    pluginId,
+    description: tool.description,
+    input_schema: tool.input_schema,
+  }));
+}
+
+/**
+ * Invoke a device tool. Never throws — every failure comes back as a typed
+ * outcome, because the caller is usually a reasoning loop that has to say
+ * something useful out loud rather than swallow an exception.
+ */
+export async function callDeviceTool(
+  name: string,
+  args: any = {},
+  opts: { timeoutMs?: number; signal?: AbortSignal } = {},
+): Promise<DeviceToolOutcome> {
+  const entry = registry.get(name);
+  if (!entry) {
+    return { ok: false, reason: 'not_found', error: `No device tool registered as "${name}"` };
+  }
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  try {
+    const build = contextProvider || defaultContext;
+    const built = build(entry.pluginId, entry.capabilities, entry.stateDomains);
+    const ctx: DeviceToolContext = {
+      ...built,
+      // Whoever built the context, a call cannot own a subscription.
+      deviceState: withoutSubscribe(built.deviceState),
+      signal: opts.signal,
+    };
+
+    const result = await Promise.race([
+      Promise.resolve(entry.tool.run(args, ctx)),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`Device tool "${name}" timed out after ${timeoutMs}ms`)),
+          timeoutMs,
+        );
+      }),
+    ]);
+
+    return { ok: true, result };
+  } catch (err: any) {
+    const message = err?.message || String(err);
+    const timedOut = message.includes('timed out after');
+    return { ok: false, reason: timedOut ? 'timeout' : 'failed', error: message };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/** Test/host reset. */
+export function clearDeviceTools(): void {
+  registry.clear();
+}

package/src/tools/serverCalls.ts

@@ -0,0 +1,78 @@
+/**
+ * Device tools called BY THE SERVER.
+ *
+ * Two callers reach the same registered function on this phone:
+ *
+ *  - the voice loop, which already runs here (no server hop at all), and
+ *  - the server reasoning loop, which cannot execute a device tool itself and
+ *    sends it down the client's stream instead.
+ *
+ * This is the second one. It rides the transport the `ui.*` plugin commands
+ * already use — a command arrives on the job/actor stream, we run it, and post
+ * the outcome back keyed by `correlationId`. Nothing new was invented; the
+ * payload just carries a tool call instead of a UI command.
+ *
+ * The host wires this once at startup:
+ *
+ *   pluginCommandEmitter.on('plugin-command', handleServerDeviceToolCall);
+ */
+import { callDeviceTool } from './registry';
+import { ensureDeviceToolsLoaded } from './loader';
+
+type PostResult = (correlationId: string, result: any, error?: string) => Promise<void>;
+
+let postResult: PostResult | null = null;
+
+/**
+ * Host DI: how to answer the server. `@ateam-ai-mobile/core` supplies
+ * postCommandResult; kept injectable so this package stays free of the REST
+ * client and so tests can observe the answer.
+ */
+export function setDeviceToolResultPoster(fn: PostResult): void {
+  postResult = fn;
+}
+
+/** Is this stream command a device tool call? */
+export function isDeviceToolCommand(cmd: any): boolean {
+  return !!cmd && cmd.kind === 'device_tool' && typeof cmd.tool === 'string' && !!cmd.correlationId;
+}
+
+/**
+ * Run a server-dispatched device tool and answer.
+ *
+ * Never throws — the server is blocked on the correlationId, so the one thing
+ * we must not do is stay silent. Every path posts something back.
+ */
+export async function handleServerDeviceToolCall(cmd: any): Promise<void> {
+  if (!isDeviceToolCommand(cmd)) return;
+
+  const { tool, args, correlationId } = cmd;
+
+  if (!postResult) {
+    console.warn('[deviceTools] server called a tool but no result poster is installed');
+    return;
+  }
+
+  try {
+    // The server may reach us before anything opened a voice call, so the
+    // plugins may not be loaded yet. Cheap and idempotent once warm.
+    await ensureDeviceToolsLoaded();
+
+    const outcome = await callDeviceTool(tool, args || {});
+    console.log(`[deviceTools] server-called ${tool} → ${outcome.ok ? 'ok' : outcome.reason}`);
+
+    await postResult(
+      correlationId,
+      outcome.ok ? { ok: true, ...unwrap(outcome.result) } : undefined,
+      outcome.ok ? undefined : outcome.error,
+    );
+  } catch (err: any) {
+    await postResult(correlationId, undefined, err?.message || String(err)).catch(() => {});
+  }
+}
+
+/** Keep an object result flat for the reasoning loop; wrap anything else. */
+function unwrap(result: any): Record<string, any> {
+  if (result && typeof result === 'object' && !Array.isArray(result)) return result;
+  return { result };
+}