@graineai/inapp-react-native 0.22.0 → 0.24.0

package/INTEGRATION.md

@@ -507,6 +507,7 @@ useGraineEvents((e) => {
     case "conversation_ended":   analytics.track("agent_call_ended", { reason: e.reason }); break;
     case "agent_volunteered":    analytics.track("agent_spoke_first"); break;
     case "action_requested":     analytics.track("agent_action", { name: e.name }); break;
+    case "action_completed":     analytics.track("agent_action_result", { name: e.name, status: e.status }); break;
   }
 });
 ```
@@ -765,6 +766,109 @@ and resamples in its output stage, which is where the artefacts came from.
 
 ---
 
+## Friction detection
+
+The agent speaks up when the customer looks stuck — before they say so. The
+SDK reads what your screens already report and turns it into five signals:
+
+| Signal | Fires when |
+|---|---|
+| `stalled_on_step` | untouched for `idle.afterMs` (a stuck field is named) |
+| `repeated_field_error` | the same field shows an error `count` times in `windowMs` |
+| `looping_between_screens` | back on the same screen `visits` times in `windowMs` |
+| `rage_taps` | a `useGraineTap`-tracked tap `taps` times in `windowMs` |
+| `screen_error` | the screen reports an `error` banner |
+
+Each is sent to the agent as an `app_event` (it still decides whether to
+speak, within `nudge.cooldownSeconds` / `nudge.maxPerSession`) and to your app
+as `friction_detected` on `useGraineEvents`.
+
+**Configure it in the dashboard** — Agent → Embed & Widgets → Friction — and
+every install picks it up with the session. Or pass rules from the app for the
+screens only it knows about; the app's layer wins:
+
+```tsx
+<GraineProvider client={client} friction={{
+  screens: {
+    terms: { ignore: true },                       // reading is not stuck
+    otp:   { idle: { afterMs: 20000 },
+             message: "The customer has been on the OTP screen {seconds}s without entering a code." },
+    home:  { idle: false },
+  },
+  nudge: { openLauncher: true },                   // your app decides what "open" means
+}}>
+```
+
+Every rule accepts `false` to switch it off; `message` templates take
+`{title} {screen} {field} {error} {count} {seconds} {tap}`. The full document
+with defaults is `DEFAULT_FRICTION`.
+
+```tsx
+useGraineEvents((e) => {
+  if (e.type === "friction_detected" && client.friction.nudge.openLauncher) openAssistant();
+});
+```
+
+## What Call History shows for an in-app conversation
+
+Every conversation lands in the dashboard's Call History with, beside the
+transcript:
+
+- **What the agent did in the app** — every action it called, the arguments,
+  whether the app accepted or refused it, and the app's own answer
+  ("Opened the privacy screen.", "I can reach: settings, favourites, …").
+- **What happened in the app** — the screens the customer moved through, the
+  taps you track with `useGraineTap`, and every friction signal, with whether
+  the agent spoke to it and, if not, why (it was mid-sentence, it had just
+  spoken, it had reached its limit).
+- **Who it was** — from `identify()`.
+
+All of it exports to CSV. Nothing needs to be instrumented beyond what the
+screens already report.
+
+## Captions on WebRTC
+
+Captions — the agent's line and what the customer is saying — reach the host
+on both transports. On WebRTC the audio carries no text, so the runtime
+mirrors the same caption frames over the control channel; a native bar using
+`onCaption` sees `role: "customer"` and `role: "agent"` lines either way.
+
+---
+
+## Coming from RevRag
+
+Same shape, different names. If you have a RevRag integration, this is the
+whole translation:
+
+| RevRag | Graine |
+| --- | --- |
+| `useInitialize({ apiKey })` → `{ isInitialized, error }` | `useGraineReady()` → `{ ready, error }` (the key goes on `GraineProvider`) |
+| `EmbedProvider navigationRef appVersion` | `GraineProvider navigationRef appVersion` |
+| `includeScreens` | `includeScreens` |
+| `embedButtonDelayMs` | `launcherDelayMs` |
+| `embedButtonVisibilityConfig` `{ defaultDelayMs, defaultInset, groups }` | `visibility` `{ defaultDelayMs, defaultInset, groups }` |
+| `EmbedButtonGroupConfig` `{ id, screens, continuity, delayMs, delayPolicy, inset }` | `LauncherGroup` — identical fields |
+| `continuous` / `perScreen` | same |
+| `perScreen` / `oncePerGroupEntry` / `oncePerAppSession` | same |
+| `EmbedButtonInset` | `LauncherInset` — same shape |
+| `EmbedButton` (mount it yourself) | `GraineLauncher` |
+| `Embed.Event(USER_DATA, { app_user_id, data })` | `useGraineIdentify()` / `client.identify({ id, name, … })` |
+| `Embed.Event(SCREEN_STATE, { screen, data })` | `useGraineScreen({ screen, fields })` |
+| `Embed.Event(CUSTOM_EVENT, data)` / `ANALYTICS_DATA` | `useGraineTrack()` / `client.track(name, data)` |
+| `embedOnAgent(AGENT_CONVERSATION_STARTED / ENDED)` | `useGraineEvents(e => e.type === "conversation_started" / "conversation_ended")` |
+| `AgentEvent.MICROPHONE_PERMISSION_DENIED` | `{ type: "mic_denied", reason }` on the same stream |
+| `AgentEvent.POPUP_MESSAGE_VISIBLE` | `{ type: "launcher_shown", screen }` |
+| `checkPermissions()` | `requestMicrophonePermission()` |
+| server `widget_config` | `appearance` from the session, via `resolveNativeAppearance` |
+| LiveKit native setup | none — see *Why there is no LiveKit step* |
+| Friction detection (dashboard switch) | Per-screen JSON rules — `friction` on the provider, or Embed & Widgets → Friction; five named signals, `friction_detected` event |
+
+Two things RevRag has that are deliberately absent: a LiveKit install step
+(audio rides a WebView on a hosted page, so audio fixes ship without an app
+release), and click tracking on every touchable by default (`useGraineTap` is
+opt-in per element, because a stream of every tap is noise the agent has to be
+told to ignore).
+
 ## Reference
 
 | Hook | For |

package/dist/client.d.ts

@@ -1,10 +1,12 @@
 import { type ActionHandler, type AppActionResult, type AppEvent, type ScreenContext } from "./protocol.js";
+import { type FrictionConfig } from "./friction.js";
 export declare const SUBPROTOCOL = "graine.embed.v1";
 export interface GraineInAppOptions {
     baseUrl: string;
     publishableKey: string;
     variables?: Record<string, string>;
     stallAfterMs?: number;
+    friction?: FrictionConfig;
     voice?: boolean;
     WebSocketImpl?: any;
     fetchImpl?: typeof fetch;
@@ -22,6 +24,7 @@ export interface SessionConfig {
         toolName?: string;
         name?: string;
     }>;
+    friction?: FrictionConfig;
 }
 export interface ActionDiagnosis {
     usable: string[];
@@ -43,17 +46,24 @@ export declare class GraineInAppClient {
     private contextTimer;
     private pendingScreen;
     private stallTimer;
-    private stallReportedFor;
+    private detector;
+    private serverFriction;
+    private appFriction;
+    private legacyStall;
     private pingTimer;
     private agentSpeaking;
     private bargedIn;
     private muted;
     private playoutClock;
     private identity;
+    private appVersion;
     private recentEvents;
     constructor(opts: GraineInAppOptions);
+    private effectiveFriction;
+    configureFriction(override: FrictionConfig | null | undefined): void;
+    get friction(): Required<FrictionConfig>;
     on(event: string, fn: Listener): () => void;
-    private emit;
+    emit(event: string, payload?: any): void;
     private get fetch();
     session(): Promise<SessionConfig>;
     checkActions(): ActionDiagnosis;
@@ -66,6 +76,7 @@ export declare class GraineInAppClient {
     executeAction(name: string, args?: Record<string, unknown>): Promise<AppActionResult>;
     private runAction;
     private invokeAction;
+    private performAction;
     get isConnected(): boolean;
     getScreen(): ScreenContext | null;
     getIdentity(): Record<string, string>;
@@ -81,9 +92,11 @@ export declare class GraineInAppClient {
     registerAction(name: string, handler: ActionHandler): () => void;
     get availableActions(): string[];
     setScreen(context: ScreenContext | null): void;
+    private dispatchFriction;
     reportEvent(event: AppEvent): void;
     track(name: string, data?: Record<string, unknown>): void;
     private scheduleScreen;
+    setAppVersion(version: string | null | undefined): void;
     buildContextFrame(): {
         type: "app_context";
         context: Record<string, unknown>;

package/dist/client.js

@@ -1,5 +1,6 @@
 import { ACTION_DEADLINE_MS, CONTEXT_THROTTLE_MS, } from "./protocol.js";
 import { maskDeep } from "./mask.js";
+import { FrictionDetector, resolveFriction } from "./friction.js";
 export const SUBPROTOCOL = "graine.embed.v1";
 const PING_MS = 25000;
 export class GraineInAppClient {
@@ -17,19 +18,38 @@ export class GraineInAppClient {
         this.contextTimer = null;
         this.pendingScreen = false;
         this.stallTimer = null;
-        this.stallReportedFor = null;
+        this.serverFriction = null;
+        this.legacyStall = false;
         this.pingTimer = null;
         this.agentSpeaking = false;
         this.bargedIn = false;
         this.muted = false;
         this.playoutClock = null;
         this.identity = {};
+        this.appVersion = null;
         this.recentEvents = [];
         if (!opts?.publishableKey)
             throw new Error("[Graine] publishableKey is required.");
         if (!opts?.baseUrl)
             throw new Error("[Graine] baseUrl is required.");
         this.opts = { stallAfterMs: 45000, ...opts };
+        this.appFriction = opts.friction;
+        this.legacyStall = "stallAfterMs" in opts;
+        this.detector = new FrictionDetector(this.effectiveFriction());
+    }
+    effectiveFriction() {
+        const legacy = this.legacyStall
+            ? { idle: this.opts.stallAfterMs && this.opts.stallAfterMs > 0 ? { afterMs: this.opts.stallAfterMs } : false }
+            : null;
+        return resolveFriction(this.serverFriction, legacy, this.appFriction);
+    }
+    configureFriction(override) {
+        this.appFriction = override ?? undefined;
+        this.detector.configure(this.effectiveFriction());
+        this.armStall();
+    }
+    get friction() {
+        return this.detector.settings;
     }
     on(event, fn) {
         if (!this.listeners.has(event))
@@ -68,6 +88,9 @@ export class GraineInAppClient {
             throw new Error(data?.error || `Embed rejected (${res.status})`);
         }
         this.config = data;
+        this.serverFriction = data && typeof data.friction === "object" ? data.friction : null;
+        this.detector.configure(this.effectiveFriction());
+        this.armStall();
         this.reportActionMismatch();
         return this.config;
     }
@@ -262,6 +285,15 @@ export class GraineInAppClient {
         this.send({ type: "app_action_result", action_id: request.action_id, ...result });
     }
     async invokeAction(request) {
+        const result = await this.performAction(request);
+        this.emit("action_result", {
+            name: request.name,
+            status: result.status,
+            ...(result.message ? { message: result.message } : {}),
+        });
+        return result;
+    }
+    async performAction(request) {
         const handler = this.actions.get(request.name);
         if (!handler) {
             return {
@@ -334,13 +366,25 @@ export class GraineInAppClient {
     setScreen(context) {
         const changedScreen = context?.screen !== this.screen?.screen;
         this.screen = context;
+        const now = Date.now();
         if (changedScreen) {
-            this.screenSince = Date.now();
-            this.stallReportedFor = null;
-            this.armStall();
+            this.screenSince = now;
         }
+        this.dispatchFriction(this.detector.onScreen(context, now));
+        this.armStall();
         this.scheduleScreen();
     }
+    dispatchFriction(signals) {
+        for (const s of signals) {
+            this.emit("friction", s);
+            this.reportEvent({
+                name: s.name,
+                detail: s.detail,
+                cooldown_seconds: s.cooldown_seconds,
+                max_per_session: s.max_per_session,
+            });
+        }
+    }
     reportEvent(event) {
         this.emit("app_event", event);
         this.send({ type: "app_event", event });
@@ -351,6 +395,7 @@ export class GraineInAppClient {
         this.recentEvents.push({ name, at: Date.now(), ...(data ? { data } : {}) });
         if (this.recentEvents.length > 10)
             this.recentEvents.shift();
+        this.dispatchFriction(this.detector.onTrack(name, Date.now()));
         if (this.screen)
             this.scheduleScreen();
     }
@@ -370,6 +415,10 @@ export class GraineInAppClient {
             }
         }, CONTEXT_THROTTLE_MS);
     }
+    setAppVersion(version) {
+        const v = version == null ? "" : String(version).trim();
+        this.appVersion = v || null;
+    }
     buildContextFrame() {
         const hasIdentity = Object.keys(this.identity).length > 0;
         if (!this.screen && !hasIdentity && this.recentEvents.length === 0)
@@ -381,6 +430,7 @@ export class GraineInAppClient {
                 ...rest,
                 ...(this.screen ? { idle_ms: Date.now() - this.screenSince } : {}),
                 ...(Object.keys(this.identity).length ? { user: this.identity } : {}),
+                ...(this.appVersion ? { app_version: this.appVersion } : {}),
                 ...(this.recentEvents.length ? { recent_events: this.recentEvents } : {}),
                 ...(this.highlightables.size ? { highlightable: [...this.highlightables] } : {}),
             }),
@@ -396,24 +446,14 @@ export class GraineInAppClient {
     }
     armStall() {
         clearTimeout(this.stallTimer);
-        const after = this.opts.stallAfterMs ?? 0;
-        if (!after || !this.screen)
+        const due = this.detector.idleDueIn(Date.now());
+        if (due === null)
             return;
-        const screenId = this.screen.screen;
         this.stallTimer = setTimeout(() => {
-            if (this.stallReportedFor === screenId)
-                return;
-            this.stallReportedFor = screenId;
-            const title = this.screen?.title ?? screenId;
-            const stuck = (this.screen?.fields ?? []).find((f) => f.status === "invalid" || f.error || f.status === "empty");
-            this.reportEvent({
-                name: "stalled_on_step",
-                detail: stuck
-                    ? `The customer has not touched the "${title}" screen for ${Math.round(after / 1000)}s. ` +
-                        `The "${stuck.label ?? stuck.name}" field is ${stuck.error ? `showing: ${stuck.error}` : stuck.status}.`
-                    : `The customer has not touched the "${title}" screen for ${Math.round(after / 1000)}s.`,
-            });
-        }, after);
+            const signal = this.detector.onIdle(Date.now());
+            if (signal)
+                this.dispatchFriction([signal]);
+        }, due);
     }
     identify(user) {
         if (!user) {
@@ -430,7 +470,9 @@ export class GraineInAppClient {
         this.scheduleScreen();
     }
     noteInteraction() {
-        this.screenSince = Date.now();
+        const now = Date.now();
+        this.screenSince = now;
+        this.detector.onInteraction(now);
         this.armStall();
     }
     say(text) {

package/dist/friction.d.ts

@@ -0,0 +1,70 @@
+import type { ScreenContext } from "./protocol.js";
+export interface IdleRule {
+    afterMs: number;
+}
+export interface RepeatedErrorsRule {
+    count: number;
+    windowMs: number;
+}
+export interface BackAndForthRule {
+    visits: number;
+    windowMs: number;
+}
+export interface RageTapsRule {
+    taps: number;
+    windowMs: number;
+}
+export interface FrictionScreenRules {
+    ignore?: boolean;
+    idle?: IdleRule | false;
+    repeatedErrors?: RepeatedErrorsRule | false;
+    backAndForth?: BackAndForthRule | false;
+    rageTaps?: RageTapsRule | false;
+    screenError?: boolean;
+    message?: string;
+}
+export interface FrictionNudge {
+    cooldownSeconds?: number;
+    maxPerSession?: number;
+    openLauncher?: boolean;
+}
+export interface FrictionConfig extends FrictionScreenRules {
+    enabled?: boolean;
+    cooldownMs?: number;
+    nudge?: FrictionNudge;
+    screens?: Record<string, FrictionScreenRules>;
+}
+export declare const DEFAULT_FRICTION: Readonly<Required<Omit<FrictionConfig, "message" | "ignore">>>;
+export declare function resolveFriction(...layers: Array<FrictionConfig | null | undefined>): Required<FrictionConfig>;
+export declare function rulesFor(config: Required<FrictionConfig>, screenId: string | null | undefined): Required<FrictionScreenRules>;
+export type FrictionKind = "stalled_on_step" | "repeated_field_error" | "looping_between_screens" | "rage_taps" | "screen_error";
+export interface FrictionSignal {
+    name: FrictionKind;
+    screen: string;
+    detail: string;
+    data: Record<string, unknown>;
+    cooldown_seconds: number;
+    max_per_session: number;
+}
+export declare class FrictionDetector {
+    private config;
+    private screen;
+    private screenSince;
+    private lastSignalAt;
+    private idleFiredFor;
+    private visits;
+    private errorHits;
+    private errorFiredFor;
+    private taps;
+    private screenErrorFiredFor;
+    constructor(config?: FrictionConfig | Required<FrictionConfig>);
+    configure(config: Required<FrictionConfig>): void;
+    get settings(): Required<FrictionConfig>;
+    private signal;
+    private active;
+    onScreen(ctx: ScreenContext | null, now: number): FrictionSignal[];
+    onInteraction(now: number): void;
+    onTrack(name: string, now: number): FrictionSignal[];
+    idleDueIn(now: number): number | null;
+    onIdle(now: number): FrictionSignal | null;
+}

package/dist/friction.js

@@ -0,0 +1,258 @@
+const DEFAULT_RULES = {
+    idle: { afterMs: 45000 },
+    repeatedErrors: { count: 2, windowMs: 60000 },
+    backAndForth: { visits: 3, windowMs: 45000 },
+    rageTaps: { taps: 4, windowMs: 1500 },
+};
+export const DEFAULT_FRICTION = Object.freeze({
+    enabled: true,
+    cooldownMs: 60000,
+    ...DEFAULT_RULES,
+    screenError: true,
+    nudge: { cooldownSeconds: 20, maxPerSession: 3, openLauncher: false },
+    screens: {},
+});
+function num(v) {
+    const n = typeof v === "string" ? Number(v) : v;
+    return typeof n === "number" && Number.isFinite(n) && n > 0 ? n : null;
+}
+function rule(raw, shape) {
+    if (raw === false)
+        return false;
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== "object")
+        return undefined;
+    const out = {};
+    for (const [k, fallback] of Object.entries(shape)) {
+        const v = num(raw[k]);
+        out[k] = v ?? fallback;
+    }
+    return out;
+}
+function screenRules(raw, base) {
+    if (!raw || typeof raw !== "object")
+        return {};
+    const r = raw;
+    const out = {};
+    if (r.ignore === true)
+        out.ignore = true;
+    const idle = rule(r.idle, base.idle || DEFAULT_RULES.idle);
+    if (idle !== undefined)
+        out.idle = idle;
+    const rep = rule(r.repeatedErrors, base.repeatedErrors || DEFAULT_RULES.repeatedErrors);
+    if (rep !== undefined)
+        out.repeatedErrors = rep;
+    const bf = rule(r.backAndForth, base.backAndForth || DEFAULT_RULES.backAndForth);
+    if (bf !== undefined)
+        out.backAndForth = bf;
+    const rage = rule(r.rageTaps, base.rageTaps || DEFAULT_RULES.rageTaps);
+    if (rage !== undefined)
+        out.rageTaps = rage;
+    if (typeof r.screenError === "boolean")
+        out.screenError = r.screenError;
+    if (typeof r.message === "string" && r.message.trim())
+        out.message = r.message.trim();
+    return out;
+}
+export function resolveFriction(...layers) {
+    let out = {
+        ...DEFAULT_FRICTION,
+        nudge: { ...DEFAULT_FRICTION.nudge },
+        screens: {},
+        ignore: false,
+        message: "",
+    };
+    for (const layer of layers) {
+        if (!layer || typeof layer !== "object")
+            continue;
+        const top = screenRules(layer, out);
+        out = { ...out, ...top };
+        if (typeof layer.enabled === "boolean")
+            out.enabled = layer.enabled;
+        const cd = num(layer.cooldownMs);
+        if (cd !== null)
+            out.cooldownMs = cd;
+        if (layer.nudge && typeof layer.nudge === "object") {
+            const n = layer.nudge;
+            out.nudge = {
+                ...out.nudge,
+                ...(num(n.cooldownSeconds) !== null ? { cooldownSeconds: num(n.cooldownSeconds) } : {}),
+                ...(num(n.maxPerSession) !== null ? { maxPerSession: num(n.maxPerSession) } : {}),
+                ...(typeof n.openLauncher === "boolean" ? { openLauncher: n.openLauncher } : {}),
+            };
+        }
+        if (layer.screens && typeof layer.screens === "object") {
+            const screens = { ...out.screens };
+            for (const [id, raw] of Object.entries(layer.screens)) {
+                if (!id)
+                    continue;
+                screens[id] = { ...(screens[id] || {}), ...screenRules(raw, out) };
+            }
+            out.screens = screens;
+        }
+    }
+    return out;
+}
+export function rulesFor(config, screenId) {
+    const over = (screenId && config.screens[screenId]) || {};
+    return {
+        ignore: over.ignore ?? false,
+        idle: over.idle ?? config.idle,
+        repeatedErrors: over.repeatedErrors ?? config.repeatedErrors,
+        backAndForth: over.backAndForth ?? config.backAndForth,
+        rageTaps: over.rageTaps ?? config.rageTaps,
+        screenError: over.screenError ?? config.screenError,
+        message: over.message ?? config.message ?? "",
+    };
+}
+function fill(template, vars) {
+    return template.replace(/\{(\w+)\}/g, (_, k) => (vars[k] === undefined || vars[k] === null ? "" : String(vars[k])));
+}
+const stuckField = (fields) => (fields ?? []).find((f) => f.status === "invalid" || f.error) ?? (fields ?? []).find((f) => f.status === "empty");
+export class FrictionDetector {
+    constructor(config) {
+        this.screen = null;
+        this.screenSince = 0;
+        this.lastSignalAt = new Map();
+        this.idleFiredFor = null;
+        this.visits = [];
+        this.errorHits = new Map();
+        this.errorFiredFor = new Set();
+        this.taps = new Map();
+        this.screenErrorFiredFor = null;
+        this.config = resolveFriction(config);
+    }
+    configure(config) {
+        this.config = config;
+    }
+    get settings() {
+        return this.config;
+    }
+    signal(name, vars, fallback, now) {
+        const screen = this.screen?.screen ?? "";
+        const last = this.lastSignalAt.get(screen) ?? -Infinity;
+        if (now - last < this.config.cooldownMs)
+            return null;
+        this.lastSignalAt.set(screen, now);
+        const rules = rulesFor(this.config, screen);
+        const all = { title: this.screen?.title ?? screen, screen, ...vars };
+        return {
+            name,
+            screen,
+            detail: rules.message ? fill(rules.message, all) : fill(fallback, all),
+            data: vars,
+            cooldown_seconds: this.config.nudge.cooldownSeconds ?? 20,
+            max_per_session: this.config.nudge.maxPerSession ?? 3,
+        };
+    }
+    active() {
+        if (!this.config.enabled || !this.screen)
+            return null;
+        const r = rulesFor(this.config, this.screen.screen);
+        return r.ignore ? null : r;
+    }
+    onScreen(ctx, now) {
+        const prev = this.screen;
+        this.screen = ctx;
+        if (!ctx)
+            return [];
+        const changed = !prev || prev.screen !== ctx.screen;
+        if (changed) {
+            this.screenSince = now;
+            this.idleFiredFor = null;
+            this.screenErrorFiredFor = null;
+            this.errorFiredFor.clear();
+            this.visits.push({ screen: ctx.screen, at: now });
+            if (this.visits.length > 50)
+                this.visits.shift();
+        }
+        const rules = this.active();
+        if (!rules)
+            return [];
+        const out = [];
+        if (changed && rules.backAndForth) {
+            const { visits, windowMs } = rules.backAndForth;
+            const recent = this.visits.filter((v) => v.screen === ctx.screen && now - v.at <= windowMs).length;
+            if (recent >= visits) {
+                const s = this.signal("looping_between_screens", { count: recent, seconds: Math.round(windowMs / 1000) }, `The customer has come back to the "{title}" screen {count} times in the last {seconds}s without getting past it.`, now);
+                if (s)
+                    out.push(s);
+            }
+        }
+        if (rules.repeatedErrors) {
+            const { count, windowMs } = rules.repeatedErrors;
+            for (const f of ctx.fields ?? []) {
+                if (!(f.status === "invalid" || f.error))
+                    continue;
+                const key = `${ctx.screen}:${f.name}`;
+                const hits = (this.errorHits.get(key) ?? []).filter((t) => now - t <= windowMs);
+                const prevField = (prev?.fields ?? []).find((p) => p.name === f.name);
+                const same = prevField && !changed && (prevField.error ?? "") === (f.error ?? "") && prevField.status === f.status;
+                if (!same)
+                    hits.push(now);
+                this.errorHits.set(key, hits);
+                if (hits.length >= count && !this.errorFiredFor.has(key)) {
+                    this.errorFiredFor.add(key);
+                    const s = this.signal("repeated_field_error", { field: f.label ?? f.name, error: f.error ?? f.status, count: hits.length }, `The "{field}" field on the "{title}" screen has rejected the customer {count} times — it is showing: {error}.`, now);
+                    if (s)
+                        out.push(s);
+                }
+            }
+        }
+        if (rules.screenError && ctx.error && this.screenErrorFiredFor !== ctx.screen) {
+            this.screenErrorFiredFor = ctx.screen;
+            const s = this.signal("screen_error", { error: ctx.error }, `The "{title}" screen is showing an error: {error}.`, now);
+            if (s)
+                out.push(s);
+        }
+        return out;
+    }
+    onInteraction(now) {
+        this.screenSince = now;
+    }
+    onTrack(name, now) {
+        const rules = this.active();
+        if (!rules || !rules.rageTaps || !this.screen)
+            return [];
+        if (!name.startsWith("tap:"))
+            return [];
+        const { taps, windowMs } = rules.rageTaps;
+        const key = `${this.screen.screen}:${name}`;
+        const times = (this.taps.get(key) ?? []).filter((t) => now - t <= windowMs);
+        times.push(now);
+        this.taps.set(key, times);
+        if (times.length < taps)
+            return [];
+        this.taps.set(key, []);
+        const s = this.signal("rage_taps", { tap: name.slice(4), count: times.length, seconds: (windowMs / 1000).toFixed(1) }, `The customer tapped "{tap}" {count} times in {seconds}s on the "{title}" screen — it may not be responding or not doing what they expect.`, now);
+        return s ? [s] : [];
+    }
+    idleDueIn(now) {
+        const rules = this.active();
+        if (!rules || !rules.idle || !this.screen)
+            return null;
+        if (this.idleFiredFor === this.screen.screen)
+            return null;
+        return Math.max(0, rules.idle.afterMs - (now - this.screenSince));
+    }
+    onIdle(now) {
+        const rules = this.active();
+        if (!rules || !rules.idle || !this.screen)
+            return null;
+        if (this.idleFiredFor === this.screen.screen)
+            return null;
+        if (now - this.screenSince < rules.idle.afterMs)
+            return null;
+        this.idleFiredFor = this.screen.screen;
+        const stuck = stuckField(this.screen.fields);
+        const seconds = Math.round(rules.idle.afterMs / 1000);
+        return this.signal("stalled_on_step", {
+            seconds,
+            field: stuck ? stuck.label ?? stuck.name : "",
+            error: stuck?.error ?? stuck?.status ?? "",
+        }, stuck
+            ? `The customer has not touched the "{title}" screen for {seconds}s. The "{field}" field is ${stuck.error ? "showing: {error}" : "{error}"}.`
+            : `The customer has not touched the "{title}" screen for {seconds}s.`, now);
+    }
+}

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export type { ActionHandler, AppActionRequest, AppActionResult, AppEvent, ScreenContext, ScreenField, } from "./protocol.js";
 export { GraineInAppClient, type GraineInAppOptions, type SessionConfig, type ActionDiagnosis, } from "./client.js";
+export { FrictionDetector, resolveFriction, rulesFor, DEFAULT_FRICTION, type FrictionConfig, type FrictionScreenRules, type FrictionNudge, type FrictionSignal, type FrictionKind, } from "./friction.js";
 export { VoiceSession, liveAudioStreamAdapter, base64ToPcm16, CAPTURE_SAMPLE_RATE, type AudioAdapter, type VoiceSessionOptions, } from "./voice.js";
 export { EchoGuard, decodeAgentAudio, decodeMuLaw, decodePcm16, base64ToBytes, type AudioFormat, type DecodedAudio, } from "./audio.js";
 export { addMaskRule, maskDeep, maskString } from "./mask.js";
-export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineTrack, useGraineTap, useGraineHighlight, useGraineWidget, type GraineEvent, type GraineProviderProps, type Turn, type Caption, } from "./react-native/index.js";
+export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineTrack, useGraineTap, useGraineHighlight, useGraineWidget, useGraineReady, type GraineEvent, type GraineProviderProps, type Turn, type Caption, } from "./react-native/index.js";
+export { requestMicrophonePermission } from "./react-native/permissions.js";
 export { resolveNativeAppearance, type NativeAppearance, type NativeAppearanceFallback, } from "./react-native/appearance.js";
 export { RtcVoiceSessionController, RtcVoiceError, type RtcVoiceState, type RtcVoiceErrorCode, type RtcVoiceSession, type RtcVoiceOptions, } from "./react-native/voice-rtc.js";
 export { GraineAgentBar, GraineLauncher, type GraineAgentBarProps, type GraineLauncherProps, type GraineBarTheme, } from "./react-native/ui.js";

package/dist/index.js

@@ -1,8 +1,10 @@
 export { GraineInAppClient, } from "./client.js";
+export { FrictionDetector, resolveFriction, rulesFor, DEFAULT_FRICTION, } from "./friction.js";
 export { VoiceSession, liveAudioStreamAdapter, base64ToPcm16, CAPTURE_SAMPLE_RATE, } from "./voice.js";
 export { EchoGuard, decodeAgentAudio, decodeMuLaw, decodePcm16, base64ToBytes, } from "./audio.js";
 export { addMaskRule, maskDeep, maskString } from "./mask.js";
-export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineTrack, useGraineTap, useGraineHighlight, useGraineWidget, } from "./react-native/index.js";
+export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineTrack, useGraineTap, useGraineHighlight, useGraineWidget, useGraineReady, } from "./react-native/index.js";
+export { requestMicrophonePermission } from "./react-native/permissions.js";
 export { resolveNativeAppearance, } from "./react-native/appearance.js";
 export { RtcVoiceSessionController, RtcVoiceError, } from "./react-native/voice-rtc.js";
 export { GraineAgentBar, GraineLauncher, } from "./react-native/ui.js";

package/dist/react-native/index.d.ts

@@ -2,6 +2,7 @@ import React from "react";
 import { GraineInAppClient, type GraineInAppOptions } from "../client.js";
 import { type AudioAdapter, type VoiceSessionOptions } from "../voice.js";
 import type { ActionHandler, ScreenContext } from "../protocol.js";
+import type { FrictionConfig } from "../friction.js";
 import { type LauncherInset, type LauncherVisibility } from "./navigation.js";
 interface GraineContextValue {
     client: GraineInAppClient;
@@ -21,6 +22,7 @@ interface GraineContextValue {
     launcherInset: LauncherInset;
     currentScreen: string | null;
     appearance: Record<string, any> | null;
+    sessionReady: boolean;
     onEvent: (fn: (e: GraineEvent) => void) => () => void;
     track: (name: string, data?: Record<string, unknown>) => void;
     identify: (user: Record<string, unknown> | null) => void;
@@ -43,12 +45,24 @@ export type GraineEvent = {
     type: "action_completed";
     name: string;
     status: string;
+    message?: string;
 } | {
     type: "muted";
     muted: boolean;
 } | {
     type: "error";
     message: string;
+} | {
+    type: "mic_denied";
+    reason: string;
+} | {
+    type: "launcher_shown";
+    screen: string | null;
+} | {
+    type: "friction_detected";
+    name: string;
+    screen: string;
+    detail: string;
 };
 export interface GraineWidget {
     id: string;
@@ -75,11 +89,13 @@ export interface GraineProviderProps extends Partial<GraineInAppOptions> {
     navigationRef?: {
         current: any;
     } | null;
+    appVersion?: string;
+    friction?: FrictionConfig;
     includeScreens?: string[];
     launcherDelayMs?: number;
     visibility?: LauncherVisibility;
 }
-export declare function GraineProvider({ children, autoConnect, onProactive, endOnBackground, navigationRef, includeScreens, launcherDelayMs, visibility, client: providedClient, ...options }: GraineProviderProps): React.JSX.Element;
+export declare function GraineProvider({ children, autoConnect, onProactive, endOnBackground, navigationRef, appVersion, friction, includeScreens, launcherDelayMs, visibility, client: providedClient, ...options }: GraineProviderProps): React.JSX.Element;
 export declare function useGraineAgent(): GraineContextValue;
 export declare function useGraineEvents(handler: (e: GraineEvent) => void): void;
 export declare function useGraineTrack(): (name: string, data?: Record<string, unknown>) => void;
@@ -101,4 +117,8 @@ export declare function useGraineWidget(): {
     dismiss: () => void;
 };
 export declare function useGraineAction(name: string, handler: ActionHandler): void;
+export declare function useGraineReady(): {
+    ready: boolean;
+    error: string | null;
+};
 export {};

package/dist/react-native/index.js

@@ -5,7 +5,7 @@ import { GraineInAppClient } from "../client.js";
 import { VoiceSession } from "../voice.js";
 import { LauncherVisibilityTracker, activeRouteName, } from "./navigation.js";
 const Ctx = createContext(null);
-export function GraineProvider({ children, autoConnect = true, onProactive, endOnBackground = true, navigationRef, includeScreens, launcherDelayMs = 0, visibility, client: providedClient, ...options }) {
+export function GraineProvider({ children, autoConnect = true, onProactive, endOnBackground = true, navigationRef, appVersion, friction, includeScreens, launcherDelayMs = 0, visibility, client: providedClient, ...options }) {
     const clientRef = useRef(null);
     if (!clientRef.current) {
         clientRef.current =
@@ -37,6 +37,7 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
         return () => { listenersRef.current.delete(fn); };
     }, []);
     const [appearance, setAppearance] = useState(null);
+    const [sessionReady, setSessionReady] = useState(false);
     const [currentScreen, setCurrentScreen] = useState(null);
     const [launcherVisible, setLauncherVisible] = useState(false);
     const [launcherInset, setLauncherInset] = useState({ right: 16, bottom: 20 });
@@ -76,12 +77,14 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
             }
             if (decision.delayMs <= 0) {
                 setLauncherVisible(true);
+                emitEvent({ type: "launcher_shown", screen: route });
                 return;
             }
             setLauncherVisible(false);
             showTimerRef.current = setTimeout(() => {
                 showTimerRef.current = null;
                 setLauncherVisible(true);
+                emitEvent({ type: "launcher_shown", screen: route });
             }, decision.delayMs);
         };
         apply();
@@ -95,6 +98,9 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
                 nav.removeListener("state", apply);
         };
     }, [navigationRef, client]);
+    useEffect(() => { client.setAppVersion(appVersion); }, [client, appVersion]);
+    useEffect(() => { if (friction !== undefined)
+        client.configureFriction(friction); }, [client, friction]);
     useEffect(() => {
         if (!navigationRef?.current)
             setLauncherVisible(true);
@@ -129,6 +135,8 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
                 return [...prev, { role: "agent", text, live: true }];
             })),
             client.on("widget", (widget) => setWidgets((prev) => [...prev, widget])),
+            client.on("mic_denied", (p) => emitEvent({ type: "mic_denied", reason: String(p?.reason || "NotAllowedError") })),
+            client.on("friction", (s) => emitEvent({ type: "friction_detected", name: String(s?.name ?? ""), screen: String(s?.screen ?? ""), detail: String(s?.detail ?? "") })),
             client.on("muted", (m) => {
                 setMutedState(m);
                 emitEvent({ type: "muted", muted: m });
@@ -140,6 +148,12 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
                 emitEvent({ type: "agent_speaking", speaking });
             }),
             client.on("action", (req) => emitEvent({ type: "action_requested", name: req?.name ?? "" })),
+            client.on("action_result", (r) => emitEvent({
+                type: "action_completed",
+                name: r?.name ?? "",
+                status: r?.status ?? "unknown",
+                ...(r?.message ? { message: String(r.message) } : {}),
+            })),
             client.on("transcript", ({ text, final }) => {
                 if (text)
                     setCaption({ role: "customer", text, live: !final });
@@ -153,6 +167,7 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
                 const cfg = client.config ?? (await client.session());
                 if (cfg?.appearance)
                     setAppearance(cfg.appearance);
+                setSessionReady(true);
             }
             catch {
             }
@@ -234,11 +249,12 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
         launcherInset,
         currentScreen,
         appearance,
+        sessionReady,
         onEvent,
         track: (name, data) => client.track(name, data),
         identify: (user) => client.identify(user),
     }), [client, connected, connecting, error, open, messages, widgets, muted, agentSpeaking, caption,
-        launcherVisible, launcherInset, currentScreen, onEvent, appearance]);
+        launcherVisible, launcherInset, currentScreen, onEvent, appearance, sessionReady]);
     return _jsx(Ctx.Provider, { value: value, children: children });
 }
 function useGraine() {
@@ -368,3 +384,7 @@ export function useGraineAction(name, handler) {
     handlerRef.current = handler;
     useEffect(() => client.registerAction(name, (args) => handlerRef.current(args)), [client, name]);
 }
+export function useGraineReady() {
+    const { sessionReady, error } = useGraineAgent();
+    return { ready: sessionReady, error };
+}

package/dist/react-native/permissions.d.ts

@@ -0,0 +1,5 @@
+export declare function requestMicrophonePermission(rationale?: {
+    title?: string;
+    message?: string;
+    buttonPositive?: string;
+}): Promise<boolean>;

package/dist/react-native/permissions.js

@@ -0,0 +1,21 @@
+import { PermissionsAndroid, Platform } from "react-native";
+export async function requestMicrophonePermission(rationale = {}) {
+    if (Platform.OS !== "android")
+        return true;
+    try {
+        const perm = PermissionsAndroid?.PERMISSIONS?.RECORD_AUDIO;
+        if (!perm)
+            return true;
+        if (await PermissionsAndroid.check(perm))
+            return true;
+        const res = await PermissionsAndroid.request(perm, {
+            title: rationale.title ?? "Microphone",
+            message: rationale.message ?? "Allow the microphone so you can talk to the assistant.",
+            buttonPositive: rationale.buttonPositive ?? "Allow",
+        });
+        return res === PermissionsAndroid.RESULTS.GRANTED;
+    }
+    catch {
+        return true;
+    }
+}

package/dist/react-native/voice-launcher.js

@@ -1,7 +1,8 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState } from "react";
-import { AppState, PermissionsAndroid, Platform, View } from "react-native";
+import { AppState, View } from "react-native";
 import { useGraineAgent } from "./index.js";
+import { requestMicrophonePermission } from "./permissions.js";
 export function GraineVoiceLauncher({ webView: WebView, autoStart = false, transport, onTransport, onCaption, onCallState, onMicDenied, onError, onEnded, children, }) {
     const { client, appearance } = useGraineAgent();
     const ref = useRef(null);
@@ -34,26 +35,7 @@ export function GraineVoiceLauncher({ webView: WebView, autoStart = false, trans
         })();
         return () => { cancelled = true; };
     }, [client, voiceAgentId]);
-    const ensureMic = useCallback(async () => {
-        if (Platform.OS !== "android")
-            return true;
-        try {
-            const perm = PermissionsAndroid?.PERMISSIONS?.RECORD_AUDIO;
-            if (!perm)
-                return true;
-            if (await PermissionsAndroid.check(perm))
-                return true;
-            const res = await PermissionsAndroid.request(perm, {
-                title: "Microphone",
-                message: "Allow the microphone so you can talk to the assistant.",
-                buttonPositive: "Allow",
-            });
-            return res === PermissionsAndroid.RESULTS.GRANTED;
-        }
-        catch {
-            return true;
-        }
-    }, []);
+    const ensureMic = useCallback(() => requestMicrophonePermission(), []);
     const pushContext = useCallback(() => {
         const frame = client.buildContextFrame();
         if (!frame)
@@ -80,6 +62,7 @@ export function GraineVoiceLauncher({ webView: WebView, autoStart = false, trans
         if (!(await ensureMic())) {
             setConnecting(false);
             onMicDenied?.("NotAllowedError");
+            client.emit("mic_denied", { reason: "NotAllowedError" });
             return;
         }
         post({ type: "graine:start-call" });
@@ -155,6 +138,7 @@ export function GraineVoiceLauncher({ webView: WebView, autoStart = false, trans
                 onEnded?.();
                 return;
             case "graine:mic-denied":
+                client.emit("mic_denied", { reason: String(msg.reason || "NotAllowedError") });
                 onMicDenied?.(String(msg.reason || "denied"));
                 return;
             case "graine:widget": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graineai/inapp-react-native",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "type": "module",
   "description": "Graine in-app agent for React Native — an agent that sees the screen your customer is on and can act on it.",
   "license": "MIT",