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

package/dist/index.d.mts

@@ -5,12 +5,1185 @@ import * as react_native from 'react-native';
 import { View, TextInput } from 'react-native';
 export { ActivityIndicator, Animated, FlatList, Image, Modal, Platform, Pressable, RefreshControl, ScrollView, SectionList, StyleSheet, Switch, Text, TextInput, TouchableOpacity, View } from 'react-native';
 
+/**
+ * @adas/device-state — Device Bridge v2, the SEMANTIC layer.
+ *
+ * Intended repo path:
+ *   packages/plugin-runtime/src/sdk/device-state.ts
+ * Intended module specifier for plugin bundles:
+ *   '@adas/device-state'   (NOT '@adas/plugin-sdk')
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * WHICH LAYER AM I IN?
+ *
+ *   props.device.*        MECHANICAL. "Do this to the hardware, now."
+ *                         VERB names: takePhoto, getCurrent, scanBarcode,
+ *                         readOnce, authenticate, pickImage.
+ *                         Returns a BARE value. THROWS when it cannot.
+ *                         Declared in the manifest as `capabilities: { camera: true }`
+ *                         (the legacy `native: {}` field is still honoured).
+ *                         Lives in '@adas/plugin-sdk'.
+ *
+ *   props.deviceState.*   SEMANTIC. "What is true right now, and how well do
+ *                         we know it?"
+ *                         STATE names: getSnapshot, subscribe, start, stop.
+ *                         Returns a SNAPSHOT carrying freshness + confidence,
+ *                         and able to say `unknown` in every field.
+ *                         A read NEVER throws for absence.
+ *                         Declared in the manifest as `stateDomains: ['visual']`.
+ *                         Lives in '@adas/device-state' (this file).
+ *
+ * The two containers are the discriminator. Every semantic call in a plugin
+ * begins with the eight characters `deviceState.`; every mechanical call
+ * begins with `native.`. There is no line of code where the layer is
+ * ambiguous, and no object on which both appear.
+ *
+ * This is a deliberate departure from
+ * Docs/device-bridge-v2/DEVICE_BRIDGE_V2_IMPLEMENTATION_GROUNDING_2026-08-07.md
+ * §"Migration strategy", which proposed adding `visual`, `spatial`,
+ * `connectivityState`… as fields ON `PluginNative`. See the design note at the
+ * bottom of this file for why that layout is rejected and what it costs.
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * PROVENANCE MARKERS used throughout. They are not decoration — the freeze
+ * really does fix some of this and really does leave the rest open, and an
+ * implementor needs to know which is which before changing a line:
+ *
+ *   FROZEN   — API_FREEZE 2026-08-07 §15 lists it as a frozen candidate.
+ *   V0.1     — "v0.1 freeze candidate; may change only when implementation
+ *              grounding proves a field impossible/non-portable."
+ *   OPEN     — the docs explicitly leave it undecided. Do not quietly close it.
+ *   DECISION — not in the docs at all; decided here, and reversible.
+ */
+/** FROZEN (API_FREEZE §1). The eight domain keys. */
+type DeviceBridgeDomain = 'spatial' | 'visual' | 'activity' | 'deviceContext' | 'connectivity' | 'capability' | 'environment' | 'interaction';
+type FreshnessState = 'fresh' | 'aging' | 'stale' | 'unknown';
+/**
+ * FROZEN. Both fields are nullable on purpose: "we have no observation at all"
+ * has to be expressible without inventing a timestamp.
+ *
+ * `aging` is a real third state, not a rounding of fresh/stale — a consumer
+ * that only branches on fresh-vs-stale is misreading the contract.
+ *
+ * API_FREEZE §1 "Why observedAt + ageMs": the host may compute `ageMs` at read
+ * time, so it can be more accurate than `Date.now() - observedAt` measured on
+ * the JS side after a bridge hop. Read `ageMs` when you have it.
+ */
+interface Freshness {
+    state: FreshnessState;
+    /** Epoch ms of the observation itself. `null` = never observed. */
+    observedAt: number | null;
+    /** Age at read time. `null` = never observed. */
+    ageMs: number | null;
+}
+type ConfidenceLevel = 'high' | 'medium' | 'low' | 'unknown';
+/**
+ * FROZEN. `level` is mandatory and ordinal; `score` is optional and exists
+ * only "when a stable numeric estimate exists" (API_FREEZE §1).
+ *
+ * The asymmetry is the point: native must not manufacture 0.5 to fill a field.
+ * A missing `score` is information — it says the estimator has no calibrated
+ * number, only a bucket.
+ */
+interface Confidence {
+    level: ConfidenceLevel;
+    /** 0..1. Omitted when no stable numeric estimate exists. */
+    score?: number;
+}
+/**
+ * FROZEN. Every snapshot in v2 carries exactly one of these.
+ *
+ * `freshness` required, `confidence` optional — because some domains report
+ * exact OS facts (battery level, audio route) where a confidence is
+ * meaningless, and others report inference (activity, indoor/outdoor) where it
+ * is mandatory. Cross-domain review: "Freshness is mandatory for dynamic
+ * state. Confidence is mandatory for inferred/estimated state; optional for
+ * exact OS facts."
+ *
+ * NOTE (OPEN): freshness is per-SNAPSHOT, never per-field. So a snapshot
+ * cannot today say "lighting is fresh but acoustics is stale". The
+ * architecture doc raised this for Spatial and Environment and never resolved
+ * it. Do not work around it by inventing a second freshness field.
+ */
+interface StateQuality {
+    freshness: Freshness;
+    confidence?: Confidence;
+}
+type SupportState = 'supported' | 'unsupported' | 'unknown';
+type PermissionState$1 = 'granted' | 'denied' | 'restricted' | 'notDetermined' | 'limited' | 'unavailable' | 'unknown';
+type AvailabilityState = 'available' | 'busy' | 'temporarilyUnavailable' | 'unavailable' | 'unknown';
+type RestrictionState = 'none' | 'backgroundRestricted' | 'systemRestricted' | 'policyRestricted' | 'lowPowerRestricted' | 'unknown';
+/**
+ * FROZEN (API_FREEZE core rule 4): "Events are meaningful semantic changes,
+ * 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, TPayload = unknown> {
+    domain: DeviceBridgeDomain;
+    name: TName;
+    /** Epoch ms. */
+    timestamp: number;
+    /**
+     * OPEN: per-event payload schemas are not specified anywhere in the three
+     * 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?: TPayload;
+}
+interface Subscription {
+    unsubscribe(): void;
+}
+type StateListener<TName extends string = string> = (event: StateEvent<TName>) => void;
+/**
+ * VOCABULARY §"Event Naming Rule", expressed as a type.
+ *
+ * Four domains (visual, activity, spatial, deviceContext) have NO frozen event
+ * vocabulary — the vocabulary doc publishes "Initial … Events" lists for
+ * 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 — 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';
+/**
+ * FROZEN shape (API_FREEZE §12).
+ *
+ * READ THE SCOPE LINE CAREFULLY. This is for FAILED OPERATIONS —
+ * `visual.capture()`, `visual.start()`. It is NOT how the surface reports that
+ * a camera is denied or a sensor is missing: "Expected state should still be
+ * exposed in snapshots."
+ *
+ * So: `getSnapshot()` does not throw this. `capture()` and `start()` do.
+ * That split is the whole no-fabrication contract in one sentence — a read
+ * always returns something honest, an action either happens or explains
+ * itself in a typed code.
+ */
+declare class DeviceBridgeError extends Error {
+    readonly code: DeviceBridgeErrorCode;
+    readonly domain?: DeviceBridgeDomain;
+    /** Whether retrying could plausibly succeed (BUSY yes, UNSUPPORTED no). */
+    readonly recoverable?: boolean;
+    constructor(code: DeviceBridgeErrorCode, message: string, opts?: {
+        domain?: DeviceBridgeDomain;
+        recoverable?: boolean;
+    });
+}
+interface StateSession {
+    id: string;
+    /** The intent this session was started with. */
+    intent: string;
+    startedAt: number;
+}
+interface StartOptions<TIntent extends string> {
+    /**
+     * MANDATORY, and that is the single most important line in this file.
+     *
+     * You cannot open a v2 session without naming what it is FOR. Native then
+     * owns sampling rate, resolution, buffering, fusion and power — API_FREEZE
+     * core rule 6. `start()` means "maintain state according to this intent",
+     * not "open a particular native API" (§2).
+     *
+     * Contrast the mechanical layer, where `camera.takePhoto()` is a legal,
+     * complete, intent-free call. That difference is visible at every call site.
+     */
+    intent: TIntent;
+    /**
+     * DECISION (not frozen). §13 requires bounded timeout/cancellation for
+     * session starts and says chain STOP must propagate to native, but leaves
+     * the plumbing "implementation-specific". `AbortSignal` is what
+     * `DeviceToolContext.signal` already carries in this SDK, so reuse it rather
+     * than invent a second cancellation idiom.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * FROZEN pattern (API_FREEZE §2), reproduced as documentation. The eight
+ * concrete domains below do NOT extend this — each spells out exactly the
+ * methods it has, because §11 warns "domains should not be forced to implement
+ * meaningless lifecycle methods" and three domains genuinely have no intent
+ * vocabulary at all.
+ *
+ * Two invariants apply to every domain:
+ *  - `getSnapshot()` reads CACHED state. It must not trigger expensive raw
+ *    sensing (no camera open, no network probe, no GPS cold start).
+ *  - "Multiple plugins may eventually share one native engine; session
+ *    ownership must not imply duplicate sensor pipelines." (OPEN: the
+ *    arbitration mechanism is undefined. See DESIGN NOTE 3.)
+ */
+interface StatefulDomain<TSnapshot, TIntent extends string = never, TEvent extends string = string> {
+    getSnapshot(): Promise<TSnapshot>;
+    start?(options: StartOptions<TIntent>): Promise<StateSession>;
+    stop?(sessionId?: string): Promise<void>;
+    subscribe?(listener: StateListener<TEvent>): Subscription;
+}
+/**
+ * Why every read is `Promise<T>` even though it is a cached read.
+ *
+ * Not because it samples — it must not. Because it crosses the RN bridge, and
+ * this SDK has no synchronous JSI module today (verified: everything in
+ * PluginNative except haptics/connectivity.isOnline is Promise-based). The
+ * grounding doc's own target for a warm cached snapshot is p50 < 10 ms /
+ * p95 < 30 ms, which is an async-bridge budget, not a sampling budget.
+ */
+/**
+ * FROZEN (API_FREEZE §3). Copied verbatim, not designed here.
+ *
+ * This landed as a placeholder first, on the belief that §3's field schema had
+ * never been written. It had — the placeholder was a gap in what got read, not
+ * a gap in the freeze. Worth recording, because "the docs leave this open" and
+ * "I did not find it" produce identical-looking comments and only one of them
+ * is a reason to invent a shape.
+ */
+type SpatialIntent = 'navigation' | 'fitness' | 'geofence' | 'lowPowerTracking' | 'preciseLocate';
+/** FROZEN (API_FREEZE §3). */
+interface SpatialPoint {
+    latitude: number;
+    longitude: number;
+    altitude?: number | null;
+    /** Metres. `null` when the platform gives no estimate — never 0, which
+     *  would read as a perfect fix. */
+    accuracyM?: number | null;
+    timestamp: number;
+}
+/** FROZEN (API_FREEZE §3). */
+interface SpatialSnapshot {
+    /** `null` when there is no usable fix. Not a zero coordinate — (0,0) is a
+     *  real place in the Gulf of Guinea. */
+    position: SpatialPoint | null;
+    movement: {
+        speedMps: number | null;
+        bearingDeg: number | null;
+        distanceRecentM: number | null;
+        state?: 'stationary' | 'moving' | 'unknown';
+    };
+    orientation: {
+        headingDeg: number | null;
+        headingAccuracyDeg?: number | null;
+        pitchDeg?: number | null;
+        rollDeg?: number | null;
+    };
+    /** Newest last. Empty when nothing has been recorded — the ring is a native
+     *  concern, and its window is chosen by intent. */
+    recentPath: SpatialPoint[];
+    changes?: {
+        lastMeaningfulTurnDeg?: number | null;
+        timestamp?: number | null;
+    };
+    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>;
+    /**
+     * 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';
+/**
+ * Media crosses by REFERENCE, never as inline bytes (core rule 3).
+ *
+ * AN ID AND NOTHING ELSE. The `uri` field is gone (2026-08-16), and its
+ * removal answers the question this comment used to record as OPEN — "how does
+ * a plugin turn a handle into pixels?" It doesn't. Ever.
+ *
+ * Frames now live in a native ring keyed by id and are never written to disk.
+ * `native.vision.readText/describe/assessQuality` take this id and resolve it
+ * INSIDE the trusted layer; the pixels do not cross into plugin code, so a
+ * solution's bundle cannot copy, upload or retain them. That is what makes
+ * "frames never leave the phone" enforceable rather than a promise.
+ *
+ * Do not add `uri` or `bytes` back. A plugin that believes it needs the pixels
+ * needs a new method on `native.vision` instead — one whose implementation
+ * stays on this side of the boundary.
+ */
+interface MediaHandle {
+    id: string;
+    mimeType?: string;
+    /**
+     * Epoch ms after which this id no longer resolves — the frame's real
+     * eviction time from the native ring, not a guess.
+     *
+     * Past it, `native.vision` throws rather than returning an empty result:
+     * "I cannot look at that frame" and "I looked and found nothing" are
+     * different answers and must never be confused by a caller about to speak.
+     * In practice a caller rarely hits this, because the timeline is clamped to
+     * native retention — see `visualEngine.effectiveWindowMs()`.
+     */
+    expiresAt?: number | null;
+}
+/**
+ * V0.1. Per-frame usability is CATEGORICAL, not numeric — 'degraded' rather
+ * than a blur score. Coarse honest classes beat false precision; the same
+ * principle the connectivity doc states outright for connection quality.
+ *
+ * Every member carries `'unknown'` so a platform that cannot assess blur says
+ * so instead of defaulting to 'good'.
+ */
+interface VisualFrameQuality {
+    blur?: 'good' | 'degraded' | 'unknown';
+    exposure?: 'good' | 'dark' | 'bright' | 'unknown';
+    /** `null` = cannot tell. Distinct from `false` = checked, not obstructed. */
+    obstructed?: boolean | null;
+}
+interface VisualFrameRef {
+    handle: MediaHandle;
+    timestamp: number;
+    orientation?: {
+        headingDeg?: number;
+        pitchDeg?: number;
+        rollDeg?: number;
+    };
+    quality?: VisualFrameQuality;
+}
+interface VisualSnapshot {
+    camera: {
+        available: boolean;
+        /**
+         * Independent of `available` on purpose. A camera can be present and
+         * permitted (`available: true`) while no session is running
+         * (`active: false`) — that is a different situation from a camera the app
+         * cannot use at all, and Guide has to say different things about them.
+         *
+         * DRIFT (flagged, not resolved): the architecture doc's conceptual block
+         * also carried `camera.orientation`; the frozen §4 block does not. Not
+         * added here.
+         */
+        active: boolean;
+        facing?: 'front' | 'back' | 'unknown';
+    };
+    /**
+     * `null` when there is no usable current frame.
+     *
+     * This is the anti-fabrication field. The alternative implementation —
+     * returning the last frame you happen to still hold — is precisely how a
+     * guidance loop ends up describing a corridor the user left thirty seconds
+     * ago. If it is not current, it is `null`, and the timeline below is where
+     * you go looking for history, knowingly.
+     */
+    latest: VisualFrameRef | null;
+    /**
+     * TIME-based, not frame-count-based. Default window ~5s; documented bounded
+     * range roughly 1–15s, selected by profile/intent. Native decides how
+     * densely to retain frames inside the window and evicts everything outside
+     * it automatically.
+     *
+     * `windowMs` is exposed; FPS knobs are NOT, and must never be added
+     * (API_FREEZE §4). If a plugin wants "more frames", it declares a different
+     * intent — it does not turn a dial.
+     */
+    recentTimeline: {
+        windowMs: number;
+        frames: VisualFrameRef[];
+    };
+    quality: StateQuality;
+}
+interface VisualCaptureResult {
+    frame: VisualFrameRef;
+}
+/**
+ * OPEN, worth knowing before you use it: whether `capture({intent})` may pass
+ * an intent DIFFERENT from the running session's intent is not addressed
+ * anywhere in the three docs.
+ */
+interface VisualCaptureOptions {
+    intent: VisualIntent;
+    /** §13: capture must support bounded timeout/cancellation. */
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+interface VisualDomain {
+    /**
+     * Cached read. Does NOT open the camera and does NOT take a picture.
+     *
+     * This is the call a guidance loop makes on every turn. The hot path is:
+     * native camera pipeline → rolling native timeline → cached visual state →
+     * one snapshot read from RN. "Avoid repeatedly starting the camera or
+     * capturing a new image for every plugin-tool call during an interactive
+     * session."
+     */
+    getSnapshot(): Promise<VisualSnapshot>;
+    /** Maintain visual state according to this intent. Not "open the camera". */
+    start(options: StartOptions<VisualIntent>): Promise<StateSession>;
+    /**
+     * An intentional, one-shot, high-quality-ish acquisition. THROWS
+     * DeviceBridgeError on failure — it is an operation, not a read.
+     *
+     * If you are about to call this once per conversational turn, stop: that is
+     * `getSnapshot()`'s job, and doing it here is the frame-timer pattern this
+     * whole layer exists to replace.
+     */
+    capture(options: VisualCaptureOptions): Promise<VisualCaptureResult>;
+    /**
+     * OPEN (doc conflict): the architecture doc shows `visual.subscribe(events)`
+     * — a filter — while API_FREEZE shows `visual.subscribe(listener)`. The
+     * freeze is followed here. Unresolved.
+     *
+     * OPEN: there is no "Initial Visual Events" list anywhere. The candidate set
+     * in prose (camera became available/unavailable, frame quality degraded/
+     * recovered, camera appears obstructed, significant scene change, visual
+     * session suspended/resumed, visual state became stale) is NOT a minted
+     * vocabulary. Typed against the naming rule only.
+     */
+    subscribe(listener: StateListener<ConformingEventName>): Subscription;
+    stop(sessionId?: string): Promise<void>;
+}
+/** FROZEN (API_FREEZE §5, VOCABULARY §"Human Activity Values"). */
+type HumanActivity = 'stationary' | 'walking' | 'running' | 'cycling' | 'driving' | 'unknown';
+/** FROZEN. Independent of HumanActivity — walking+pocket, driving+mounted. */
+type DevicePlacement = 'handheld' | 'pocket' | 'table' | 'mounted' | 'unknown';
+/**
+ * FROZEN. Note `driving` is BOTH an intent here and a HumanActivity value
+ * above. The docs define no relationship between the two and do not flag the
+ * collision: declaring intent `driving` does not assert the user is driving.
+ */
+type ActivityIntent = 'navigation' | 'fitness' | 'driving' | 'safety' | 'accessibility' | 'lowPower';
+interface ActivitySnapshot {
+    human: {
+        state: HumanActivity;
+        /** `null` when the start of the current activity is not known. */
+        since: number | null;
+        /** REQUIRED, unlike StateQuality.confidence — an inferred activity may
+         *  never be handed over without saying how sure the inference is. */
+        confidence: Confidence;
+    };
+    devicePose: {
+        placement: DevicePlacement;
+        /** V0.1. These four values appear only in the freeze TS, not in the
+         *  vocabulary doc — unlike the placement values. Mild drift, flagged. */
+        orientation?: 'portrait' | 'landscape' | 'flat' | 'unknown';
+        confidence: Confidence;
+    };
+    /**
+     * Advisory only. `likelyNext` is a hint and never a fact.
+     * OPEN: transition names are bare `string` — no controlled vocabulary exists
+     * anywhere, which sits awkwardly beside "Intents are not arbitrary strings".
+     */
+    transition?: {
+        current?: string | null;
+        likelyNext?: string | null;
+        confidence?: Confidence;
+    };
+    /** OPEN: no window length or cap is specified for Activity (Spatial gets
+     *  ~10–20s, Visual ~5s). Required array — an empty one is a real answer. */
+    recentTransitions: Array<{
+        name: string;
+        timestamp: number;
+    }>;
+    quality: StateQuality;
+}
+interface ActivityDomain {
+    getSnapshot(): Promise<ActivitySnapshot>;
+    /**
+     * OPEN: §11's naming list shows only `activity.getSnapshot()`, and §2 makes
+     * start/stop optional. Whether Activity is session-based or a passive
+     * always-on domain is genuinely unstated. Included here because the six
+     * frozen ActivityIntent values would otherwise have no seam to arrive
+     * through — but this is a DECISION, not a reading of the freeze.
+     */
+    start(options: StartOptions<ActivityIntent>): Promise<StateSession>;
+    stop(sessionId?: string): Promise<void>;
+    /** OPEN: no "Initial Activity Events" list exists. */
+    subscribe(listener: StateListener<ConformingEventName>): Subscription;
+}
+interface DeviceContextSnapshot {
+    power: {
+        /** 0..1 FRACTION, not a percentage. `null` = not known. */
+        batteryLevel: number | null;
+        charging: boolean | null;
+        lowPowerMode: boolean | null;
+    };
+    thermal: {
+        state: 'nominal' | 'fair' | 'serious' | 'critical' | 'unknown';
+    };
+    resources: {
+        memoryPressure?: 'normal' | 'warning' | 'critical' | 'unknown';
+        storagePressure?: 'normal' | 'warning' | 'critical' | 'unknown';
+    };
+    /** Confidence is legitimately omitted here — these are exact OS facts, not
+     *  estimates. Freshness still matters: a populated batteryLevel says nothing
+     *  about whether it was sampled a second or a minute ago. */
+    quality: StateQuality;
+}
+/**
+ * NO INTENT TYPE, and that is deliberate — not an oversight, and not a gap to
+ * fill in later. There is no `DeviceContextIntent` in the freeze and no
+ * "Device Context Intents" section in the vocabulary, because
+ * (cross-domain review) "A domain may expose an intent only if it changes
+ * native implementation strategy in a meaningful way." Reading battery and
+ * thermal does not.
+ *
+ * The direction of flow is the other way round: Device Context is an INPUT to
+ * how OTHER domains satisfy their intents. Visual intent `navigation` +
+ * device context `battery 5% + low-power mode` → native picks a lower-power
+ * camera strategy while still honouring the Visual contract. The plugin does
+ * not retune anything, and must not be asked to.
+ *
+ * Do not add `deviceContext.start({intent:'lowPower'})` because five other
+ * domains have a lowPower intent.
+ */
+interface DeviceContextDomain {
+    getSnapshot(): Promise<DeviceContextSnapshot>;
+    /**
+     * OPEN: `DeviceContextDomain`'s interface body is never written in the
+     * freeze, and no Device Context event names are frozen (the vocabulary has
+     * "Initial … Events" for connectivity/capability/interaction/environment
+     * only). DECISION: expose subscribe, because the candidate events —
+     * low-power mode changed, charging changed, thermal pressure changed — are
+     * exactly what an adaptive session needs and polling for them is wasteful.
+     *
+     * OPEN: "battery crossed significant threshold" and "changed materially"
+     * have no numbers anywhere, and Device Context has no profiles to
+     * parameterize them.
+     */
+    subscribe(listener: StateListener<ConformingEventName>): Subscription;
+}
+/** FROZEN (API_FREEZE §7, VOCABULARY §"Connectivity Intents"). */
+type ConnectivityIntent = 'lowLatencyConversation' | 'interactive' | 'bulkTransfer' | 'backgroundSync' | 'offlineResilient' | 'lowPower';
+/**
+ * V0.1, and note it is FLAT — the connectivity design doc sketched a nested
+ * shape (internet{…}, quality{…}, recent_history{…}) and the freeze flattened
+ * it. Two unreconciled deltas, carried here as-is rather than merged:
+ *  - `bandwidthClass` appears in the freeze but in neither the design doc nor
+ *    the vocabulary's Connectivity Values.
+ *  - there is NO recent-history field, although the design doc requires native
+ *    to maintain recent transitions and leaves the default window OPEN.
+ */
+interface ConnectivitySnapshot {
+    /** NOTE: the design doc says "online / offline / uncertain"; the frozen
+     *  third value is `unknown`. The two words are never reconciled. */
+    reachability: 'online' | 'offline' | 'unknown';
+    transport: 'wifi' | 'cellular' | 'ethernet' | 'other' | 'none' | 'unknown';
+    qualityClass: 'excellent' | 'good' | 'degraded' | 'poor' | 'unusable' | 'unknown';
+    stability: 'stable' | 'changing' | 'flapping' | 'unknown';
+    /** `null` when no recent measurement exists. Explicitly preferred over
+     *  reporting a stale number: "return unknown rather than stale precision." */
+    latencyMs?: number | null;
+    bandwidthClass?: 'high' | 'medium' | 'low' | 'unknown';
+    metered?: boolean | null;
+    constrained?: boolean | null;
+    quality: StateQuality;
+}
+/** FROZEN v0.1 (VOCABULARY §"Initial Connectivity Events"). All ten. */
+type ConnectivityEvent = 'connectivityOnline' | 'connectivityOffline' | 'transportChanged' | 'connectivityDegraded' | 'connectivityRecovered' | 'connectivityUnstable' | 'connectivityStable' | 'meteredStateChanged' | 'constrainedStateChanged' | 'connectivityStateStale';
+interface ConnectivityDomain {
+    /**
+     * A fast local cached read. It must NOT ping, and must NOT run a bandwidth
+     * or speed test. Latency is sampled on native's own schedule, chosen by
+     * intent, and cached with a timestamp.
+     */
+    getSnapshot(): Promise<ConnectivitySnapshot>;
+    /**
+     * OPEN: `ConnectivityDomain` is named in §11 but never defined, so whether
+     * connectivity is session-based is unstated. DECISION: yes — six frozen
+     * intents with documented behavioural differences (lowLatencyConversation
+     * "prioritize fresh latency knowledge"; lowPower "rely primarily on passive
+     * OS signals and minimize active probes") only mean something if there is a
+     * way to declare one.
+     */
+    start(options: StartOptions<ConnectivityIntent>): Promise<StateSession>;
+    stop(sessionId?: string): Promise<void>;
+    subscribe(listener: StateListener<ConnectivityEvent>): Subscription;
+}
+/**
+ * FROZEN. Four independent axes, deliberately not collapsed. The canonical
+ * worked example from the capability doc: supported + granted + busy + none —
+ * a camera you own, are allowed to use, and cannot have right now.
+ */
+interface CapabilityStatus {
+    support: SupportState;
+    permission?: PermissionState$1;
+    availability: AvailabilityState;
+    restriction?: RestrictionState;
+}
+interface CapabilitySnapshot {
+    camera: CapabilityStatus;
+    microphone: CapabilityStatus;
+    /** The only capability the freeze gives scoped detail to. Health and
+     *  photos/media do NOT get one — see the gap note below. */
+    location: CapabilityStatus & {
+        precision?: 'precise' | 'approximate' | 'unknown';
+        backgroundPermission?: PermissionState$1;
+    };
+    motion: CapabilityStatus;
+    bluetooth: CapabilityStatus;
+    uwb: CapabilityStatus;
+    nfc: CapabilityStatus;
+    notifications: CapabilityStatus;
+    /**
+     * GAP (flagged): the capability doc notes health "authorization is often
+     * record-type specific rather than a single global permission" and its
+     * candidate shape had a `permission_summary`. The frozen §9 gives health a
+     * plain CapabilityStatus, so scoped health authorization is NOT
+     * representable in v0.1. Its own exit criterion ("scoped permissions are
+     * representable") is therefore only partly met.
+     */
+    health: CapabilityStatus;
+    backgroundExecution: CapabilityStatus;
+    /** GAP (flagged): photos/media appears in the design doc's native inputs and
+     *  its full-vs-limited scope discussion, but there is NO photos key in the
+     *  frozen CapabilitySnapshot. Not added here. */
+    quality: StateQuality;
+}
+/** FROZEN v0.1 (VOCABULARY §"Initial Capability Events"). All ten. */
+type CapabilityEvent = 'capabilityChanged' | 'permissionChanged' | 'capabilityAvailable' | 'capabilityUnavailable'
+/** NOTE: this pair does not match the documented naming patterns. The docs
+ *  neither flag nor reconcile it; carried verbatim rather than "fixed". */
+ | 'capabilityBusy' | 'capabilityFree' | 'restrictionChanged' | 'locationPrecisionChanged' | 'backgroundPermissionChanged' | 'capabilityStateStale';
+/**
+ * NO INTENT TYPE — the one domain that is intent-less by explicit reasoning
+ * rather than by omission: "Capability State itself should generally be cheap
+ * and mostly event-driven, so it does not need many sensing profiles."
+ * A candidate `interactive/background/minimal` vocabulary is floated in the
+ * design doc and explicitly conditional ("only be kept if implementation
+ * proves they add value"). Nothing frozen. Not added.
+ *
+ * Also NOT here: any `requestPermission()`. Permission-request UX is outside
+ * this state engine by design, and a floated generic primitive is future work.
+ */
+interface CapabilityDomain {
+    getSnapshot(): Promise<CapabilitySnapshot>;
+    subscribe(listener: StateListener<CapabilityEvent>): Subscription;
+}
+/** FROZEN (VOCABULARY §"Environment Intents"). */
+type EnvironmentIntent = 'ambient' | 'navigation' | 'accessibility' | 'proximity' | 'safety' | 'lowPower';
+interface EnvironmentSnapshot {
+    /** Privacy is part of the SHAPE, not advice: this says `dim`, never a camera
+     *  frame; `loud`, never microphone audio; a beacon count, never a BLE
+     *  payload. Raw audio/images/BLE payloads are not part of this domain. */
+    lighting: {
+        level: 'dark' | 'dim' | 'normal' | 'bright' | 'veryBright' | 'unknown';
+        lux?: number | null;
+        confidence?: Confidence;
+    };
+    acoustics: {
+        level: 'quiet' | 'moderate' | 'loud' | 'veryLoud' | 'unknown';
+        approximateDb?: number | null;
+        confidence?: Confidence;
+    };
+    /** `uncertain` and `unknown` are different: uncertain = we looked and cannot
+     *  decide; unknown = we have no basis to decide. */
+    enclosure: {
+        state: 'indoor' | 'outdoor' | 'uncertain' | 'unknown';
+        confidence?: Confidence;
+    };
+    proximity?: {
+        distanceClass?: 'immediate' | 'near' | 'far' | 'unknown';
+        confidence?: Confidence;
+    };
+    /** The only sub-block with no confidence — these are presence booleans, not
+     *  estimates. Note they cannot distinguish unsupported / denied / switched
+     *  off; that distinction lives in `capability`. */
+    nearbySignals?: {
+        bleAvailable?: boolean;
+        beaconCount?: number | null;
+        uwbAvailable?: boolean;
+        nfcAvailable?: boolean;
+    };
+    quality: StateQuality;
+}
+/** FROZEN v0.1 (VOCABULARY §"Initial Environment Events"). All ten. */
+type EnvironmentEvent = 'lightingChanged' | 'environmentBecameDark' | 'environmentBecameBright' | 'noiseLevelChanged' | 'environmentBecameLoud' | 'indoorOutdoorChanged' | 'proximityChanged' | 'nearbySignalAppeared' | 'nearbySignalDisappeared' | 'environmentStateStale';
+interface EnvironmentDomain {
+    getSnapshot(): Promise<EnvironmentSnapshot>;
+    start(options: StartOptions<EnvironmentIntent>): Promise<StateSession>;
+    stop(sessionId?: string): Promise<void>;
+    subscribe(listener: StateListener<EnvironmentEvent>): Subscription;
+}
+interface InteractionSnapshot {
+    lifecycle: {
+        appState: 'foreground' | 'background' | 'inactive' | 'unknown';
+        screenOn: boolean | null;
+        userActive?: boolean | null;
+        idleDurationMs?: number | null;
+    };
+    audio: {
+        captureActive: boolean | null;
+        playbackActive: boolean | null;
+        route: 'speaker' | 'earpiece' | 'wiredHeadset' | 'bluetooth' | 'carAudio' | 'other' | 'unknown';
+        /** `none` (checked, nothing interrupting) and `unknown` (no knowledge) are
+         *  deliberately different values. */
+        interruption: 'none' | 'temporary' | 'system' | 'unknown';
+    };
+    /** Optional GROUP: a platform that cannot report voice session state omits
+     *  the whole block rather than guessing `false` for each field. */
+    voice?: {
+        sessionActive: boolean | null;
+        userSpeaking?: boolean | null;
+        assistantSpeaking?: boolean | null;
+    };
+    /** May report that a camera session is running; must NOT duplicate frame
+     *  state. Frames belong to `visual`. */
+    visual?: {
+        cameraSessionActive: boolean | null;
+    };
+    quality: StateQuality;
+}
+/** FROZEN v0.1 (VOCABULARY §"Initial Interaction Events"). All twelve. */
+type InteractionEvent = 'appStateChanged' | 'screenStateChanged' | 'audioRouteChanged' | 'audioInterruptionStarted' | 'audioInterruptionEnded' | 'voiceSessionStarted' | 'voiceSessionStopped' | 'cameraSessionStarted' | 'cameraSessionStopped' | 'userBecameActive' | 'userBecameIdle' | 'interactionStateStale';
+/**
+ * NO INTENT TYPE. §10 declares only `InteractionSnapshot`, and the vocabulary
+ * — which does publish intents for spatial, visual, activity, connectivity and
+ * environment — has no "Interaction Intents" section. Five profiles are
+ * floated in the design doc, hedged twice ("Likely profiles, if needed") with
+ * no obligation attached to any of them. Not added.
+ */
+interface InteractionDomain {
+    getSnapshot(): Promise<InteractionSnapshot>;
+    subscribe(listener: StateListener<InteractionEvent>): Subscription;
+}
+/**
+ * FROZEN name (API_FREEZE §11) and FROZEN member names.
+ *
+ * §11's "Recommended naming rule" says to call it `visual.getSnapshot()`, not
+ * `device.visual.*`. Read here as a rule about the WIRE/tool-name convention
+ * (`device.*` stays a human/backend routing convention for callable plugin
+ * tools) rather than a ban on a plugin-prop container. That reading is a
+ * judgement call and is flagged as such — if it is wrong, the fix is to rename
+ * the PROP, never to merge these eight members into `PluginNative`.
+ */
+interface DeviceBridgeV2 {
+    readonly spatial: SpatialDomain;
+    readonly visual: VisualDomain;
+    readonly activity: ActivityDomain;
+    readonly deviceContext: DeviceContextDomain;
+    readonly connectivity: ConnectivityDomain;
+    readonly capability: CapabilityDomain;
+    readonly environment: EnvironmentDomain;
+    readonly interaction: InteractionDomain;
+}
+/** The name plugin authors see. See DESIGN NOTE 1 for why not `deviceBridge`. */
+type DeviceState = DeviceBridgeV2;
+/**
+ * DECISION (not in the docs). A second, differently-named manifest field, so a
+ * plugin cannot half-declare its way across the boundary:
+ *
+ *   native:       { camera: true }        → props.device.camera.takePhoto()
+ *   stateDomains: ['visual', 'spatial']   → props.deviceState.visual.getSnapshot()
+ *
+ * Declaring `native.camera` grants NOTHING in the semantic layer, and vice
+ * versa. There is no field whose meaning spans both.
+ *
+ * How an UNDECLARED domain must behave — and this is the load-bearing part:
+ * it returns a normal snapshot in which every enum is `unknown`, every
+ * nullable is `null`, and `quality.freshness` is
+ * `{ state:'unknown', observedAt:null, ageMs:null }`. It does NOT throw and it
+ * does NOT return undefined.
+ *
+ * Why that matters here specifically: today's `gatePluginNative` gives an
+ * undeclared capability a proxy whose methods `console.warn` and return
+ * `undefined` (packages/plugin-runtime/src/host.ts:67-76). So
+ * `await native.location.getCurrent()` on an undeclared plugin resolves to
+ * `undefined`, and `pos?.latitude` is `undefined` — which then flows into an
+ * LLM answer as a confident nothing. A silent undefined is a fabrication
+ * vector; a snapshot of explicit unknowns is not.
+ *
+ * The "why" is readable from `capability.getSnapshot()` using an existing
+ * frozen enum member: a manifest-gate denial maps to
+ * `restriction: 'policyRestricted'` — the plugin manifest IS a policy. No new
+ * vocabulary needed. (The docs never consider a manifest gate, so this
+ * mapping is a DECISION, but it uses only frozen values.)
+ */
+type StateDomainDeclaration = readonly DeviceBridgeDomain[];
+/**
+ * Is this snapshot good enough to act on?
+ *
+ * Deliberately requires the caller to state a budget: there is no universal
+ * "fresh enough", and the docs give no numeric thresholds for any domain
+ * (native chooses sampling behaviour). A guidance loop wants ~1500 ms; a
+ * battery-aware background job is happy with 60 s.
+ *
+ * `unknown` freshness fails: it means nothing was ever observed, which is not
+ * the same as an old-but-real reading and must not be treated as one.
+ */
+declare function isActionable(quality: StateQuality, budget: {
+    maxAgeMs: number;
+    minConfidence?: ConfidenceLevel;
+}): boolean;
+/** The honest "we have never observed this" value. Use it instead of
+ *  inventing a timestamp when constructing a degraded snapshot. This is the
+ *  canonical source of the `unknown` freshness shape — the engine's
+ *  `qualityUnknown()` derives from it so the two never drift. */
+declare function neverObserved(): Freshness;
+/**
+ * One human-readable sentence for why a capability cannot answer, built ONLY
+ * from what the four axes actually say. Returns null when the capability is
+ * fine — so a caller cannot accidentally print a reason that does not exist.
+ */
+declare function explainCapability(status: CapabilityStatus): string | null;
+/**
+ * Additive extension of `PluginProps` (sdk/types.ts:259).
+ *
+ * `deviceState` is OPTIONAL because a host that has not installed a v2
+ * provider must not pretend to have one. `undefined` means "this host has no
+ * semantic layer", which a plugin can check once; it does NOT mean "the
+ * sensors said nothing". Those are different, and collapsing them would
+ * reintroduce exactly the ambiguity this file exists to remove.
+ */
+interface PluginPropsV2Extension {
+    readonly deviceState?: DeviceState;
+}
+/**
+ * Additive extension of `DeviceToolContext` (sdk/types.ts:320-327).
+ *
+ * This is the seam that matters most: device tools are what the AI calls, and
+ * device tools are where a fabricated value reaches a user. The lint rule
+ * proposed alongside this file (`no-mechanical-sensing-in-device-tools`) bans
+ * `ctx.native.camera`, `ctx.native.location` and `ctx.native.connectivity`
+ * inside a `DeviceToolDefinition.run` body — a device tool must reach sensing
+ * through `ctx.deviceState`. UI code is unaffected.
+ */
+interface DeviceToolContextV2Extension {
+    readonly deviceState?: DeviceState;
+}
+
+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;
+type deviceState_CapabilitySnapshot = CapabilitySnapshot;
+type deviceState_CapabilityStatus = CapabilityStatus;
+type deviceState_Confidence = Confidence;
+type deviceState_ConfidenceLevel = ConfidenceLevel;
+type deviceState_ConformingEventName = ConformingEventName;
+type deviceState_ConnectivityDomain = ConnectivityDomain;
+type deviceState_ConnectivityEvent = ConnectivityEvent;
+type deviceState_ConnectivityIntent = ConnectivityIntent;
+type deviceState_ConnectivitySnapshot = ConnectivitySnapshot;
+type deviceState_DeviceBridgeDomain = DeviceBridgeDomain;
+type deviceState_DeviceBridgeError = DeviceBridgeError;
+declare const deviceState_DeviceBridgeError: typeof DeviceBridgeError;
+type deviceState_DeviceBridgeErrorCode = DeviceBridgeErrorCode;
+type deviceState_DeviceBridgeV2 = DeviceBridgeV2;
+type deviceState_DeviceContextDomain = DeviceContextDomain;
+type deviceState_DeviceContextSnapshot = DeviceContextSnapshot;
+type deviceState_DevicePlacement = DevicePlacement;
+type deviceState_DeviceState = DeviceState;
+type deviceState_DeviceToolContextV2Extension = DeviceToolContextV2Extension;
+type deviceState_EnvironmentDomain = EnvironmentDomain;
+type deviceState_EnvironmentEvent = EnvironmentEvent;
+type deviceState_EnvironmentIntent = EnvironmentIntent;
+type deviceState_EnvironmentSnapshot = EnvironmentSnapshot;
+type deviceState_Freshness = Freshness;
+type deviceState_FreshnessState = FreshnessState;
+type deviceState_HumanActivity = HumanActivity;
+type deviceState_InteractionDomain = InteractionDomain;
+type deviceState_InteractionEvent = InteractionEvent;
+type deviceState_InteractionSnapshot = InteractionSnapshot;
+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, TPayload = unknown> = StateEvent<TName, TPayload>;
+type deviceState_StateListener<TName extends string = string> = StateListener<TName>;
+type deviceState_StateQuality = StateQuality;
+type deviceState_StateSession = StateSession;
+type deviceState_StatefulDomain<TSnapshot, TIntent extends string = never, TEvent extends string = string> = StatefulDomain<TSnapshot, TIntent, TEvent>;
+type deviceState_Subscription = Subscription;
+type deviceState_SupportState = SupportState;
+type deviceState_VisualCaptureOptions = VisualCaptureOptions;
+type deviceState_VisualCaptureResult = VisualCaptureResult;
+type deviceState_VisualDomain = VisualDomain;
+type deviceState_VisualFrameQuality = VisualFrameQuality;
+type deviceState_VisualFrameRef = VisualFrameRef;
+type deviceState_VisualIntent = VisualIntent;
+type deviceState_VisualSnapshot = VisualSnapshot;
+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_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 };
+}
+
+/**
+ * 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`. */
+type VoiceState = 'idle' | 'connecting' | 'connected' | 'error';
+/** One line of the conversation. `tool` entries are device/skill tool activity. */
+interface VoiceTranscriptEntry {
+    role: 'user' | 'ai' | 'tool';
+    text: string;
+    ts: number;
+}
+/** A point-in-time read of the session — what a reasoning loop polls. */
+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;
+}
+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,
+ * `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.
+ */
+type VoiceEvent = {
+    type: 'state';
+} | {
+    type: 'transcript';
+};
+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`.
+ */
+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. */
+declare const PLATFORM_VOICE_CALLER: unique symbol;
+/**
+ * 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.
+ */
+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).
+ */
+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[];
+}
+
 /**
  * @adas/plugin-sdk — Type definitions
  *
  * This is the developer contract for native mobile plugins.
  * Both UI and service plugins use these interfaces.
  */
+
 interface PluginContext {
     tenant: string;
     pluginId: string;
@@ -59,6 +1232,11 @@ interface CameraAPI {
         width: number;
         height: number;
     }>;
+    /**
+     * @deprecated Use `native.scanner.scanOnce()`. Scanning needs a MOUNTED
+     * camera, which a bare function call cannot provide; this refuses by name
+     * and points there.
+     */
     scanBarcode(opts?: {
         formats?: string[];
     }): Promise<{
@@ -70,6 +1248,26 @@ interface CameraAPI {
     }): Promise<{
         uri: string;
     }[]>;
+    /**
+     * Record a video clip the user deliberately makes — a damage claim, a
+     * how-it-sounds clip, something to attach.
+     *
+     * NOT the Visual domain. That is an ephemeral frame ring a reasoning loop
+     * reads and nobody keeps; this produces a FILE. Different jobs, and the
+     * grammar says so: this is a verb that throws, Visual is a state read that
+     * says `unknown`.
+     *
+     * Rides the same mounted camera surface as `scanner.scanOnce`, and throws
+     * the same coded failures. `withAudio` needs microphone permission and
+     * REFUSES without it rather than quietly recording silence.
+     */
+    recordVideo(opts?: {
+        maxDurationMs?: number;
+        withAudio?: boolean;
+    }): Promise<{
+        uri: string;
+        durationMs: number | null;
+    }>;
 }
 interface LocationAPI {
     getCurrent(opts?: {
@@ -124,6 +1322,16 @@ interface HapticsAPI {
     impact(style: 'light' | 'medium' | 'heavy'): void;
     notification(type: 'success' | 'warning' | 'error'): void;
     selection(): void;
+    /**
+     * Shorthand for notification('error').
+     *
+     * Documented in the platform guide and already CALLED by shipped plugins
+     * (connections-panel), which only compiled because they reached it through
+     * optional chaining — `native?.haptics?.error?.()` silently does nothing when
+     * the method is absent, so a failure the user was meant to FEEL produced no
+     * buzz and no error. Declared here so the call site is checked.
+     */
+    error(): void;
 }
 interface ConnectivityAPI {
     isOnline(): boolean;
@@ -177,6 +1385,29 @@ interface ScannerAPI {
         granted: boolean;
         status: string;
     }>;
+    /**
+     * Show the scanner and resolve with the FIRST code read.
+     *
+     * The plugin no longer mounts anything: the host renders one
+     * `CameraTaskHost`, this raises it, and the promise settles when a code is
+     * found. That is why the capture lifecycle is owned in exactly one place
+     * instead of by every plugin that wants to scan.
+     *
+     * THROWS rather than resolving empty, with a code that says which:
+     *   TIMEOUT           nothing was found in time
+     *   CANCELLED         the user dismissed it — a choice, not a fault
+     *   PERMISSION_DENIED camera permission refused
+     *   BUSY              another camera task is running
+     *   UNAVAILABLE       no camera surface is mounted in this app
+     * An empty string would read as a code that scanned to nothing.
+     */
+    scanOnce(opts?: {
+        formats?: string[];
+        timeoutMs?: number;
+    }): Promise<{
+        data: string;
+        format: string;
+    }>;
 }
 interface NfcNdefRecord {
     type: string;
@@ -212,10 +1443,235 @@ interface BiometricsAPIv2 {
         error?: string;
     }>;
 }
+interface BluetoothDevice {
+    id: string;
+    name: string | null;
+    /** Signal strength in dBm. Null when not reported — never 0, which is a
+     *  legitimate (and very strong) reading. */
+    rssi: number | null;
+    /** Manufacturer/service payload, if the advertisement carried one. */
+    serviceUUIDs?: string[];
+}
+interface VisionText {
+    /** The recognised string. */
+    text: string;
+    /** 0..1 recogniser confidence. Null when the platform gives no estimate —
+     *  never 1, which would read as certainty nothing measured. */
+    confidence: number | null;
+    /** Normalised 0..1 box in the frame, origin top-left. Lets a guide say
+     *  "the sign on your right" rather than just quoting words. */
+    box?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+interface VisionLabel {
+    /** A label from the platform's classifier vocabulary — NOT free text. */
+    label: string;
+    confidence: number | null;
+}
+interface VisionObject {
+    /** A detector-vocabulary class name (e.g. "Car", "Traffic light", "Person") —
+     *  NOT free text. */
+    label: string;
+    /** 0..1 detector confidence. Null when the platform gives no estimate — never
+     *  1, which would read as certainty nothing measured. */
+    confidence: number | null;
+    /** Normalised 0..1 box in the frame, origin top-left. Where the thing is,
+     *  so a guide can say "on your right" rather than just naming it. */
+    box?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * How usable a frame is, as measured rather than guessed.
+ *
+ * This one is the exception to the split above: it is a MEASUREMENT of the
+ * image, not an interpretation of the scene, so its results belong on
+ * `VisualFrameRef.quality` — which currently reports `unknown` for all three
+ * because nothing looks at the pixels. Wiring this is what lets a guide say
+ * "it's too dark for me to tell" instead of describing a black frame.
+ */
+interface VisionFrameQuality {
+    blur: 'sharp' | 'slight' | 'severe' | 'unknown';
+    exposure: 'good' | 'dark' | 'bright' | 'unknown';
+    /** True when the lens is covered. Null = not assessed. */
+    obstructed: boolean | null;
+}
+interface VisionAPI {
+    /** Is on-device vision available at all? False is a real answer. */
+    isSupported(): Promise<boolean>;
+    /**
+     * Read text in a frame (OCR).
+     *
+     * Returns an EMPTY ARRAY when it looked and found no text — that is a real
+     * finding, distinct from throwing, which means it could not look.
+     */
+    readText(frameId: string, opts?: {
+        languages?: string[];
+    }): Promise<VisionText[]>;
+    /**
+     * Label what is in a frame.
+     *
+     * Deliberately labels, not prose. A sentence is the SKILL's job — this layer
+     * must not put words in the model's mouth, and a classifier that returns
+     * "a bathroom sign ahead on the left" is asserting a spatial relationship it
+     * did not measure.
+     */
+    describe(frameId: string, opts?: {
+        maxLabels?: number;
+    }): Promise<VisionLabel[]>;
+    /**
+     * Detect the objects in a frame, each with a box.
+     *
+     * Distinct from `describe`: describe LABELS the whole scene ("kitchen"),
+     * detectObjects LOCATES the things in it ("Person" on the left, "Car" ahead) —
+     * which is what a guidance loop reads to say where something is. Returns an
+     * EMPTY ARRAY when it looked and found nothing, distinct from throwing (could
+     * not look). On-device (bundled detector); frames never leave the phone.
+     */
+    detectObjects(frameId: string, opts?: {
+        maxItems?: number;
+        minConfidence?: number;
+    }): Promise<VisionObject[]>;
+    /** 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>;
+    /** Is the radio switched on? (Separate from permission — both can block.) */
+    isEnabled(): Promise<boolean>;
+    /**
+     * Scan for advertising devices for `timeoutMs`, then stop.
+     *
+     * Bounded rather than open-ended on purpose: a scan left running is a
+     * battery drain the caller cannot see, and the mistake is invisible until a
+     * user notices their phone is flat.
+     */
+    scan(opts?: {
+        timeoutMs?: number;
+        serviceUUIDs?: string[];
+    }): Promise<BluetoothDevice[]>;
+}
 interface PluginNative {
     camera: CameraAPI;
     location: LocationAPI;
-    storage: StorageAPI;
+    /**
+     * @deprecated The gate never hands this out — it uses the per-plugin
+     * `storageFor(pluginId)` and FAILS CLOSED (blocks) when it can't scope. A
+     * single shared storage across plugins was a cross-plugin read/write hole;
+     * there is no shared bucket any more. Present only so older providers still
+     * satisfy the type; new providers implement `storageFor`.
+     */
+    storage?: StorageAPI;
     /** @deprecated use `biometricsV2` for the native-backed API. This stub
      *  remains for backwards compatibility. */
     biometrics: BiometricsAPI;
@@ -223,11 +1679,44 @@ interface PluginNative {
     notifications: NotificationsAPI;
     haptics: HapticsAPI;
     connectivity: ConnectivityAPI;
-    fileSystem: FileSystemAPI;
+    /**
+     * @deprecated The gate never hands this out — it uses the per-plugin
+     * `fileSystemFor(pluginId)` and FAILS CLOSED (blocks) when it can't scope. A
+     * single shared filesystem across plugins was a cross-plugin read/write hole;
+     * there is no shared bucket any more. Present only so older providers still
+     * satisfy the type; new providers implement `fileSystemFor`.
+     */
+    fileSystem?: FileSystemAPI;
+    /**
+     * Per-plugin filesystem: returns a FileSystemAPI whose sandbox root is scoped
+     * to THIS plugin (`plugin-files/<pluginId>/`), so one plugin cannot read,
+     * write or reach another plugin's files even via traversal. `gatePluginNative`
+     * uses it (passing the plugin's id) to isolate each plugin. If it is absent or
+     * no id is known, the gate FAILS CLOSED (blocks) rather than fall back to a
+     * shared filesystem — there is no shared bucket.
+     */
+    fileSystemFor?(pluginId: string): FileSystemAPI;
+    /**
+     * Per-plugin storage: returns a StorageAPI whose KV namespace AND SQLite
+     * database are scoped to THIS plugin, so one plugin cannot read, overwrite,
+     * or query another plugin's key-value entries or tables. `gatePluginNative`
+     * uses it (passing the plugin's id) to isolate each plugin. Identity is
+     * threaded through the TRUSTED provider here — never a caller-supplied
+     * key/table prefix. If it is absent or no id is known, the gate FAILS CLOSED
+     * (blocks) rather than fall back to a shared store — there is no shared bucket.
+     */
+    storageFor?(pluginId: string): StorageAPI;
     cookies: CookiesAPI;
     sharing: SharingAPI;
     scanner: ScannerAPI;
     nfc: NfcAPI;
+    /** SHAPE ONLY in this build — see BluetoothAPI. Present so it fails by name. */
+    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;
@@ -237,7 +1726,20 @@ interface NativeCapabilities$1 {
     backgroundTasks?: boolean;
     fileSystem?: boolean;
     notifications?: boolean;
+    /** BLE. Declaring it passes the gate but every call refuses by name until
+     *  the native side exists — see BluetoothAPI. */
     bluetooth?: boolean;
+    /** 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
+     *  indicator. See VoiceAPI. */
+    voice?: boolean;
     haptics?: boolean;
     /** Read the platform cookie jar after a WebView login flow. */
     cookies?: boolean;
@@ -305,7 +1807,43 @@ interface ThemeTokens {
 }
 interface PluginProps {
     bridge: PluginBridge;
-    native: PluginNative;
+    /**
+     * L2 Device Primitives — the camera/location/storage/haptics/… surface, gated
+     * to the capabilities this plugin declared. This is the canonical name (R4);
+     * the underlying L1 native modules keep the `native` name, but what a plugin
+     * receives is `props.device`.
+     */
+    device: PluginNative;
+    /**
+     * @deprecated Renamed to `device` in R4. Still passed (the SAME gated object)
+     * so existing/remote plugin bundles keep working — migrate to `props.device`.
+     */
+    native?: PluginNative;
+    /**
+     * L3 DeviceState — the SEMANTIC layer (`props.deviceState.spatial/visual/…`),
+     * gated to the domains this plugin declared in `stateDomains`. Reads answer
+     * `unknown` rather than throwing; a domain the build has no engine for, or the
+     * plugin did not declare, returns an explicit refusal.
+     *
+     * REQUIRED, deliberately: an optional field is exactly the compile-time escape
+     * hatch that let a renderer ship without it (props.deviceState === undefined,
+     * which crashed on drawer/card). Every renderer builds this through
+     * resolvePluginRuntimeProps, so the constructor side always has it; making it
+     * required means a NEW renderer that forgets to pass it fails to compile.
+     */
+    deviceState: DeviceState;
+    /**
+     * The live conversational SESSION, gated to plugins that declared
+     * `capabilities: { voice: true }`. A SESSION, not a device sensor: start/stop
+     * the loop, read + subscribe to the transcript, and speak first via
+     * `prompt()`. The mic-active indicator is platform-owned and cannot be
+     * suppressed from here.
+     *
+     * REQUIRED, like `deviceState`: every renderer builds it through
+     * resolvePluginRuntimeProps, so the object is always present. An undeclared
+     * plugin gets a refusal (reads say so, actions throw) — never a fake `idle`.
+     */
+    voice: VoiceAPI;
     theme: ThemeTokens;
     context: PluginContext;
     /** Engine-supplied props from `sys.focusUiPlugin(pluginId, props)`.
@@ -349,6 +1887,11 @@ interface PluginManifest$1 {
         actions: string[];
     };
     capabilities?: Record<string, unknown>;
+    /** L3 DeviceState domains this plugin reads (props.deviceState), as Core passes
+     *  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;
     _mcpEndpoint?: string;
@@ -357,7 +1900,13 @@ interface RegisteredUIPlugin {
     id: string;
     type: 'ui' | 'hybrid';
     capabilities?: NativeCapabilities$1;
+    /** L3 DeviceState domains this plugin's UI reads (props.deviceState). The
+     *  trusted source for a HOST-registered plugin (no server manifest), read by
+     *  resolvePluginRuntimeProps. Carried by register(), same as registerTools. */
+    stateDomains?: DeviceBridgeDomain[];
     Component: React.FC<PluginProps>;
+    /** Optional `tools/` section — a plugin may ship both UI and local tools. */
+    tools?: DeviceToolDefinition[];
 }
 interface RegisteredServicePlugin {
     id: string;
@@ -367,7 +1916,50 @@ interface RegisteredServicePlugin {
     onStart: (props: Omit<PluginProps, 'theme'>) => Promise<void> | void;
     onStop?: () => Promise<void> | void;
 }
-type RegisteredPlugin = RegisteredUIPlugin | RegisteredServicePlugin;
+/** What a device tool implementation is handed at call time. */
+interface DeviceToolContext {
+    bridge: PluginBridge;
+    /** Device Bridge — camera, location, sensors, storage. */
+    native: PluginNative;
+    /**
+     * L3 semantic DeviceState (visual/spatial/activity/…), gated to the domains
+     * the plugin declared in `stateDomains`. Every domain is always present; an
+     * undeclared one answers with an explicit "not declared" rather than data —
+     * 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. */
+    signal?: AbortSignal;
+}
+type DeviceToolFn = (args: any, ctx: DeviceToolContext) => Promise<any> | any;
+interface DeviceToolDefinition {
+    /** Domain name, as the catalog and the caller see it. e.g. "guide.observe" */
+    name: string;
+    description?: string;
+    /** JSON Schema for arguments — advertised to Core, not enforced here. */
+    input_schema?: Record<string, unknown>;
+    run: DeviceToolFn;
+}
+/** A plugin that ships tools and no UI at all. */
+interface RegisteredToolsPlugin {
+    id: string;
+    type: 'tools';
+    capabilities?: NativeCapabilities$1;
+    /**
+     * 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[];
+}
+type RegisteredPlugin = RegisteredUIPlugin | RegisteredServicePlugin | RegisteredToolsPlugin;
 
 /**
  * Plugin registration API.
@@ -376,12 +1968,35 @@ type RegisteredPlugin = RegisteredUIPlugin | RegisteredServicePlugin;
 
 /**
  * Register a UI or hybrid plugin (has a visual component).
+ *
+ * `tools` is optional: a plugin may ship UI and local tools together. Tools are
+ * picked up when the bundle loads, independently of whether the UI is mounted.
  */
 declare function register(id: string, config: {
     type?: 'ui' | 'hybrid';
     capabilities?: NativeCapabilities$1;
+    /** L3 DeviceState domains this plugin's UI reads via props.deviceState (e.g.
+     *  ['spatial','visual']). Carried through so a HOST-registered plugin (no
+     *  server manifest) can declare its domains — resolvePluginRuntimeProps reads
+     *  this as the trusted source when there is no manifest. Dropping it here left
+     *  every registered UI plugin with no L3, silently. Mirrors registerTools. */
+    stateDomains?: DeviceBridgeDomain[];
     Component: React.FC<PluginProps>;
+    tools?: DeviceToolDefinition[];
 }): RegisteredUIPlugin;
+/**
+ * Register a tools-only plugin — a `tools/` section with no UI at all.
+ *
+ * Nothing here mounts. The tools become callable as soon as the bundle is
+ * evaluated, and stay callable with nothing of the plugin on screen.
+ */
+declare function registerTools(id: string, config: {
+    capabilities?: NativeCapabilities$1;
+    /** 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;
 /**
  * Register a headless service plugin (no UI).
  */
@@ -460,6 +2075,20 @@ interface ActionButtonProps {
 }
 declare function ActionButton({ theme, label, icon, onPress, style }: ActionButtonProps): React$1.FunctionComponentElement<react_native.PressableProps & React$1.RefAttributes<View>>;
 
+interface CameraPreviewProps {
+    /**
+     * The plugin's own `props.native`. REQUIRED, and it is the gate: the runtime
+     * stamps the declared capabilities onto this object, so passing it is how the
+     * component knows whether this plugin may show a camera at all.
+     */
+    native: PluginNative;
+    facing?: 'front' | 'back';
+    style?: any;
+    /** Rendered instead of the built-in panel when the preview is unavailable. */
+    renderUnavailable?: (reason: string) => React$1.ReactElement | null;
+}
+declare function CameraPreview({ native, facing, style, renderUnavailable }: CameraPreviewProps): react_jsx_runtime.JSX.Element | null;
+
 type ThemeColors = ThemeTokens['colors'];
 /** Override the plugin theme (host brand). Call once at startup — mounted
  *  plugins re-render with the new tokens. */
@@ -486,8 +2115,88 @@ declare function useApi(bridge: PluginBridge): PluginApi;
 declare const PluginSDK: {
     readonly register: typeof register;
     readonly registerService: typeof registerService;
+    readonly registerTools: typeof registerTools;
 };
 
+/**
+ * Host DI for the SEMANTIC layer — the `props.deviceState` counterpart of
+ * `setPluginNativeProvider`.
+ *
+ * Kept in its own file rather than added to host.ts, for the same reason the
+ * two layers have separate namespaces: the moment they share a module, the
+ * next person adds a domain to `PluginNative` or a capability to
+ * `stateDomains` and the boundary starts to blur.
+ *
+ * THE GATE IS NOT THE MECHANICAL ONE. `gatePluginNative` replaces an
+ * undeclared capability with a proxy whose methods warn and return `undefined`
+ * — so `await native.location.getCurrent()` resolves to `undefined`, and
+ * `pos?.latitude` is `undefined`, which flows into a model answer as a
+ * confident nothing. A silent undefined is a fabrication vector.
+ *
+ * Here, an undeclared domain returns a real snapshot in which everything is
+ * explicitly `unknown` / `null`, with `freshness.state = 'unknown'`. The
+ * plugin gets a well-formed answer that says "I know nothing", which no
+ * reasonable code path can mistake for data.
+ */
+
+/** Host DI: the app supplies the engines it has. Called once at startup. */
+declare function setDeviceStateProvider(state: Partial<DeviceState>): void;
+/**
+ * The `deviceState` a plugin receives, gated by what it declared.
+ *
+ * Every domain is always present — a plugin can call any of the eight without
+ * an existence check. What differs is whether it answers with data, or with
+ * an explicit "I know nothing" and a reason.
+ */
+declare function gateDeviceState(declared?: readonly DeviceBridgeDomain[]): DeviceState;
+/** Which domains this build can actually answer — for diagnostics. */
+declare function implementedStateDomains(): DeviceBridgeDomain[];
+
+/**
+ * Host DI + gate for `props.voice` — the session counterpart of
+ * setDeviceStateProvider / setPluginNativeProvider.
+ *
+ * The app mounts one live voice session (VoiceSessionHost in @ateam-ai-mobile/ui)
+ * and hands it here once at startup via setVoiceProvider. gateVoice then decides,
+ * per plugin, whether that session is exposed:
+ *
+ *  - declared (`capabilities: { voice: true }`) + a provider present → the real
+ *    session.
+ *  - declared but no provider (no session host in this build) → a refusal that
+ *    names the reason.
+ *  - NOT declared → a refusal that names the reason.
+ *
+ * ABSENCE IS AN ANSWER (spec invariant 6). A denied surface never fakes an
+ * `idle` snapshot and never silently no-ops: reads report `state: 'error'` with
+ * an explicit `lastError`, and actions throw. A silent `idle` would read to a
+ * reasoning loop as "a working session that simply isn't connected yet" — a
+ * fabrication, the same class of bug as an undefined that flows into an answer.
+ */
+
+/** Host DI: the app supplies its live (owner-aware) voice session. Called once
+ *  at startup; pass null to detach (e.g. in a build with no voice). */
+declare function setVoiceProvider(provider: VoiceSessionProvider | null): void;
+/** Whether this build has a voice session to expose — for diagnostics. */
+declare function implementedVoice(): boolean;
+/**
+ * The `voice` a plugin receives, gated by whether it declared the capability AND
+ * scoped to its identity.
+ *
+ * `declared` is `!!capabilities.voice` from the plugin's TRUSTED declaration
+ * (resolved in pluginRuntime.ts — the server manifest for a remote plugin, the
+ * registry entry for a host-owned one). A downloaded bundle cannot grant itself
+ * voice. `pluginId` is the trusted identity the returned facade is bound to.
+ *
+ * Reading the transcript of a live session is a privacy surface, not just an
+ * API: this gate is the only thing between a plugin and everything the user
+ * says. Two protections stack: (1) it is coupled to evidence — a live session
+ * shows the platform-owned, unsuppressable mic indicator, so there is no path to
+ * a transcript without visible proof the mic is/was live; and (2) it is scoped
+ * to the owner, so declaring `voice` lets a plugin run ITS OWN conversation, not
+ * eavesdrop on another solution's. A missing identity FAILS CLOSED.
+ */
+declare function gateVoice(declared: boolean, pluginId: string): VoiceAPI;
+
 /**
  * Host integration points — the DI seams that keep this package free of
  * Expo imports. The host app (or @ateam-ai-mobile/expo) plugs in concrete providers
@@ -500,7 +2209,8 @@ declare function setHapticsProvider(haptics: HapticsAPI | null): void;
 /** No-op safe accessor — surfaces call this for tap feedback. */
 declare function getHaptics(): HapticsAPI | null;
 /** Install the device-capabilities implementation plugins receive as
- *  `props.native`. The host owns the native modules. */
+ *  `props.device` (the L1 native modules keep the `native` name; the plugin-
+ *  facing prop is `device`). The host owns the native modules. */
 declare function setPluginNativeProvider(native: PluginNative): void;
 declare function getPluginNative(): PluginNative;
 /**
@@ -512,7 +2222,18 @@ declare function getPluginNative(): PluginNative;
  * Flag mapping mirrors the manifest contract: `storage` is gated by
  * `offline` (offline data ⇒ local storage).
  */
-declare function gatePluginNative(native: PluginNative, declared?: NativeCapabilities$1): PluginNative;
+declare function gatePluginNative(native: PluginNative, declared?: NativeCapabilities$1, pluginId?: string): PluginNative;
+/** Props the host's preview implementation receives. */
+interface CameraPreviewImplProps {
+    facing?: 'front' | 'back';
+    style?: any;
+    renderUnavailable?: (reason: string) => any;
+}
+/** Install the host's camera preview (e.g. an expo-camera CameraView). */
+declare function setCameraPreviewProvider(Component: ((props: CameraPreviewImplProps) => any) | null): void;
+/** Null when the host installed none — the SDK then renders a stated reason,
+ *  never a black rectangle that looks like a dark room. */
+declare function getCameraPreviewProvider(): ((props: CameraPreviewImplProps) => any) | null;
 type PluginResolver = RegisteredPlugin | (() => Promise<RegisteredPlugin | null>);
 declare function registerNativePlugin(id: string, plugin: PluginResolver): void;
 declare function unregisterNativePlugin(id: string): void;
@@ -522,11 +2243,262 @@ declare const nativePluginRegistry: {
 };
 declare function registerBundleModules(modules: Record<string, any>): void;
 
+/** The gated surface a plugin Component receives. `device` and `native` are the
+ *  SAME object (native is the deprecated alias). */
+interface PluginRuntimeProps {
+    device: PluginNative;
+    native: PluginNative;
+    deviceState: DeviceState;
+    voice: VoiceAPI;
+}
+/** One declaration source — either the server manifest or the registry entry. */
+interface PluginDeclaration {
+    capabilities?: NativeCapabilities$1 | Record<string, unknown>;
+    native?: NativeCapabilities$1;
+    stateDomains?: readonly DeviceBridgeDomain[];
+}
+interface PluginRuntimeSource {
+    pluginId: string;
+    /**
+     * The server manifest (Core-passed) — the TRUSTED authority for a REMOTE
+     * plugin. `capabilities` is the current field Core emits; `native` is the
+     * legacy one. A grant absent here is NOT GRANTED (fail closed).
+     */
+    manifest?: PluginDeclaration | null;
+    /**
+     * The registry entry — the trusted authority for a HOST-OWNED plugin
+     * (registered locally, no server manifest). For a REMOTE plugin this is the
+     * downloaded bundle's own claim and is UNTRUSTED for gating; it is used ONLY
+     * when there is no manifest.
+     */
+    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[];
+}
+/**
+ * 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
+ * mixed, and a remote plugin's own downloaded bundle claim NEVER expands its
+ * capabilities or L3 domains past what the trusted source granted. If the
+ * trusted source omits a grant, it is not granted — fail closed. (If Core does
+ * 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 {
+    name: string;
+    pluginId: string;
+    description?: string;
+    input_schema?: Record<string, unknown>;
+}
+type DeviceToolOutcome = {
+    ok: true;
+    result: any;
+} | {
+    ok: false;
+    error: string;
+    reason: 'not_found' | 'no_context' | 'timeout' | 'failed';
+};
+/**
+ * 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.
+ */
+declare function setDeviceToolContextProvider(fn: (pluginId: string, capabilities?: NativeCapabilities$1, stateDomains?: DeviceBridgeDomain[]) => DeviceToolContext): void;
+/**
+ * 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.
+ */
+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;
+/** 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
+ * outcome, because the caller is usually a reasoning loop that has to say
+ * something useful out loud rather than swallow an exception.
+ */
+declare function callDeviceTool(name: string, args?: any, opts?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<DeviceToolOutcome>;
+/** Test/host reset. */
+declare function clearDeviceTools(): void;
+
+/**
+ * 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).
+ */
+declare function ensureDeviceToolsLoaded({ force }?: {
+    force?: boolean | undefined;
+}): Promise<string[]>;
+/** Forget that we loaded, so the next call re-reads the catalog. */
+declare function resetDeviceToolLoader(): void;
+
+declare function registerPlatformDeviceTools(): void;
+
+interface SessionSnapshot {
+    authenticated: boolean;
+    /** The tenant the session is scoped to (derive it; never a stored copy). */
+    tenant: string | null;
+}
+type DeviceToolsAction = 'load' | 'reset' | 'none';
+/**
+ * PURE: what should the device-tool registry do for this session transition?
+ * - a new authenticated tenant (initial sign-in OR a switch) → 'load'
+ * - the same authenticated tenant again (e.g. a silent token refresh) → 'none'
+ * - leaving authenticated (sign-out) → 'reset'
+ */
+declare function deviceToolsActionForSession(next: SessionSnapshot, prevTenant: string | null): {
+    action: DeviceToolsAction;
+    tenant: string | null;
+};
+/** The effects a session transition drives — injected so a test can fake them. */
+interface DeviceToolsSessionDeps {
+    /** Drop the previous tenant's device tools (a switch does not run logout teardown). */
+    clear: () => void;
+    /** Ensure the static, host-owned platform device tools are present. */
+    registerPlatform: () => void;
+    /** Forget the "already loaded" latch so a later (non-forced) load runs — sign-out. */
+    resetLoader: () => void;
+    /** Fire-and-forget reload of the current tenant's external device-tool bundles. */
+    load: () => void;
+}
+/**
+ * Apply a session transition to the device-tool registry. Call from the host's
+ * existing auth-session subscription with a derived snapshot. Idempotent per
+ * tenant: repeated snapshots for the same authenticated tenant do nothing, so a
+ * silent token refresh does not churn the registry. Returns the action taken.
+ */
+declare function syncDeviceToolsForSession(next: SessionSnapshot, deps?: DeviceToolsSessionDeps): DeviceToolsAction;
+/** Test seam: forget the last-seen tenant so a test starts from signed-out. */
+declare function __resetSessionSyncForTest(): void;
+
+type PostResult = (correlationId: string, result: any, error?: string) => Promise<void>;
+/**
+ * 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.
+ */
+declare function setDeviceToolResultPoster(fn: PostResult): void;
+/** Is this stream command a device tool call? */
+declare function isDeviceToolCommand(cmd: any): boolean;
+/**
+ * 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.
+ */
+declare function handleServerDeviceToolCall(cmd: any): Promise<void>;
+
+/** Where the bytes currently running came from. */
+type LoadedBundleSource = 'download' | 'disk-cache' | 'memory';
+/**
+ * Provenance of one loaded bundle — what is RUNNING, not what was requested.
+ *
+ * `hash` is the sha256 of the evaluated bytes. `expected` is the hash the
+ * server's manifest advertised for that url. Equal means the phone is running
+ * the build the server currently describes; different means it is not, and the
+ * pair says so without needing a rebuild, a reinstall or a guess.
+ */
+interface LoadedBundleInfo {
+    bundleUrl: string;
+    version: string;
+    /** sha256 (hex, lowercase) of the bytes that were evaluated. */
+    hash: string | null;
+    /** sha256 the server advertised for this url at load time, if any. */
+    expected: string | null;
+    source: LoadedBundleSource;
+    tenant: string | null;
+    loadedAt: number;
+}
 declare class BundleManager {
-    /** In-memory module cache: bundleUrl → evaluated module.exports */
+    /** In-memory module cache: bundleUrl → evaluated module.exports. Holds ONE
+     *  tenant's modules at a time — the tenant boundary is `cacheTenant` /
+     *  `requireTenant()`, NOT the key. */
     private modules;
+    /** What is actually RUNNING, keyed by bundleUrl (for the current tenant). See
+     *  getLoadedBundles(). */
+    private provenance;
     /** In-flight download deduplication: bundleUrl → Promise */
     private inflight;
+    /**
+     * The tenant the in-memory caches (modules / provenance / inflight) currently
+     * belong to. This is the tenant BOUNDARY for evaluated code.
+     *
+     * A bundleUrl resolves PER-TENANT on the server — one url, different bytes for
+     * different tenants — so a memory hit keyed on url alone would hand tenant B
+     * the module tenant A already evaluated and ran. PR #9 scoped the DISK cache
+     * (per-tenant index + hash gate); the in-memory map was left url-keyed. This
+     * closes that: the caches only ever hold ONE tenant's modules, and a switch
+     * drops them before anything is served.
+     */
+    private cacheTenant;
+    /**
+     * pluginIds this manager registered device tools for. A tenant switch drops
+     * the in-memory modules AND unregisters these, so the incoming tenant's bundle
+     * re-registers into a clean registry instead of being refused as a duplicate
+     * 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.
+     *
+     * FAIL CLOSED: without a tenant identity we cannot prove a cached module is
+     * this session's, so we drop everything and refuse rather than risk serving
+     * one tenant's evaluated code to another. On a tenant change we drop the
+     * previous tenant's modules (and their tool registrations) before proceeding.
+     */
+    /**
+     * Monotonic load generation. Bumped on every in-memory wipe (a tenant change,
+     * fail-closed, or clearAll). A load captures it at ENTRY; a completion whose
+     * generation no longer matches is stale and is discarded before it can commit.
+     * This closes the async race the sequential guard cannot: tenant A's in-flight
+     * loadModule can resolve AFTER a switch to B — clearing `inflight` does not
+     * cancel that Promise — and would otherwise write A's module / provenance /
+     * device tools into the singleton now marked cacheTenant=B.
+     */
+    private epoch;
+    private requireTenant;
+    /** Drop every in-memory cache and unregister the device tools this manager
+     *  registered — used on a tenant change and by clearAll(). */
+    private dropInMemory;
+    /** True once the boundary has moved since a load captured `epoch` — i.e. a
+     *  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;
+    /** 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.
      * Handles: in-memory cache → disk cache → download → evaluate → extract.
@@ -535,8 +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 | 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
@@ -548,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).
@@ -557,7 +2549,47 @@ declare class BundleManager {
      * Clear cache for a specific plugin/bundle.
      */
     clearPlugin(pluginId: string): Promise<void>;
+    /**
+     * What every loaded bundle IS, right now: the sha256 of the bytes running,
+     * the hash the server advertised, and where they came from.
+     *
+     * Deliberately not filtered or prettified — this is the raw answer to "did my
+     * redeploy reach the phone?", and it is comparable directly against the
+     * manifest `bundleHash` and the server's X-Bundle-SHA256 header.
+     */
+    getLoadedBundles(): LoadedBundleInfo[];
     private loadModule;
+    /**
+     * 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
@@ -567,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 */
@@ -584,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;
@@ -591,6 +2628,37 @@ interface BundleCacheEntry {
     bundleUrl: string;
     /** SHA-256 (hex, lowercase) of the cached bundle bytes — integrity proof */
     bundleHash?: string;
+    /**
+     * Tenant whose session downloaded these bytes.
+     *
+     * A bundle URL is NOT tenant-independent: `/api/ui-plugins/<id>/bundle.js`
+     * resolves per-tenant on the server, so the SAME url returns different code
+     * for different tenants. On the normal load path the hash gate catches this
+     * for free — the expected hash comes from the current tenant's manifest and
+     * will not match another tenant's cached bytes. The disk-cache recovery path
+     * has no manifest to check against, so it must discriminate by tenant.
+     *
+     * Absent on entries written before this field existed: unknown ownership, so
+     * 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>>;
@@ -821,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;
@@ -1139,4 +3210,4 @@ declare function isInlineSurface(m: SurfaceManifest): m is InlineSurfaceManifest
 
 declare function SurfaceDispatcher(): react_jsx_runtime.JSX.Element;
 
-export { ActionButton, AdaOrb, type AdaOrbState, Badge, type BiometricsAPI, type BiometricsAPIv2, type Bridge, type BundleCacheEntry, type BundleStorage, type CameraAPI, Card, type ConnectivityAPI, type CookiesAPI, EmptyState, ErrorState, type FileSystemAPI, type HapticsAPI, type InlineSurfaceManifest, ListItem, LoadingState, type LocationAPI, MemoryBundleStorage, type MountSurfaceManifest, type NativeCapabilities$1 as NativeCapabilities, type NfcAPI, type NotificationsAPI, type PluginManifest as PlatformPluginManifest, type PluginBridge, type PluginContext, type PluginHooks$1 as PluginHooks, type PluginManifest$1 as PluginManifest, type PluginNative, type PluginProps, PluginSDK, type PluginSummary, type PluginSurfaceMeta, type RegisteredPlugin, type RegisteredServicePlugin, type RegisteredUIPlugin, type RemotePlugin, type RenderMode, type ScannerAPI, SearchBar, type SharingAPI, type StorageAPI, SurfaceCard, type SurfaceCardProps, SurfaceDispatcher, SurfaceDrawer, type SurfaceDrawerProps, SurfaceFullscreen, type SurfaceFullscreenProps, type SurfaceManifest, type SurfacePlacement, type SurfaceType, type SurfaceVisibility, TabBar, type ThemeTokens, bundleManager, createNativeBridge, gatePluginNative, getHaptics, getNativeBundleHash, getNativeBundleUrl, getNativeComponentId, getPlugin, getPluginNative, isInlineSurface, isMountSurface, listPlugins, nativePluginRegistry, register, registerBundleModules, registerNativePlugin, registerService, resolvePluginUrl, setBundleStorage, setHapticsProvider, setPluginNativeProvider, setPluginThemeColors, supportsNative, supportsWebView, 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 };