@appilots/sdk 0.11.3 → 0.13.0

package/dist/{index-BR-33WMN.d.ts → index-CI4jmSoP.d.ts}

@@ -1,6 +1,33 @@
 import * as React$1 from 'react';
 import React__default from 'react';
 
+/** Customer conversation/UI locales. Map text and host-app labels may use other languages. */
+declare const SUPPORTED_APPILOTS_LOCALES: readonly ["pt-BR", "en", "es", "fr"];
+type SupportedAppilotsLocale = (typeof SUPPORTED_APPILOTS_LOCALES)[number];
+
+type MissionStatus = 'awaiting_approval' | 'running' | 'paused' | 'blocked' | 'completed' | 'cancelled';
+interface MissionScope {
+    id: string;
+    revision: number;
+    operation: 'delete';
+    screen: string;
+    listId: string;
+    items: Array<{
+        key: string;
+        label: string;
+    }>;
+    expiresAt: number;
+}
+interface MissionView {
+    scope: MissionScope;
+    objective: string;
+    status: MissionStatus;
+    completed: number;
+    total: number;
+    reason?: string;
+    progressText: string;
+}
+
 /**
  * Theme tokens — the source of truth for any color, font, radius or
  * shadow used inside the SDK's chat UI. Components must read from these
@@ -132,7 +159,7 @@ declare function mergeThemeTokens(base: AppilotsThemeTokens, partial?: PartialTh
  * `i18n/bundles/` AND a branch in `i18n/I18nProvider.tsx`'s `BUNDLES`
  * map AND a variant here. BACKLOG 4.1.
  */
-type AppilotsLocale = 'pt-BR' | 'en' | 'es';
+type AppilotsLocale = SupportedAppilotsLocale;
 
 /**
  * Core types for the Appilots SDK.
@@ -282,7 +309,9 @@ interface AgentPermissions {
     blockedScreens?: string[];
     allowedActions?: AgentActionType[];
 }
-type AppilotsEventType = 'agent:action:start' | 'agent:action:complete' | 'agent:action:error' | 'agent:message' | 'navigation:change' | 'chat:open' | 'chat:close' | 'chat:escalation:start' | 'chat:escalation:message' | 'chat:escalation:end' | 'sdk:introspection:unavailable';
+type AppilotsEventType = 'agent:action:start'
+/** Queue dispatch, after approval; distinct from a proposed action. */
+ | 'agent:action:executing' | 'agent:action:complete' | 'agent:action:error' | 'agent:message' | 'navigation:change' | 'chat:open' | 'chat:close' | 'chat:cancel' | 'chat:escalation:start' | 'chat:escalation:message' | 'chat:escalation:end' | 'sdk:introspection:unavailable';
 interface AppilotsEvent {
     type: AppilotsEventType;
     timestamp: number;
@@ -301,6 +330,12 @@ interface EscalationState {
     operatorName?: string;
 }
 
+/** Optional host storage; only a session handle is stored, never screen contents. */
+interface AppilotsSessionStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
 /**
  * Mirrors `introspectionDiagnosticsSchema` on the wire. Declared here
  * rather than imported so client-core stays free of the server's
@@ -315,6 +350,7 @@ interface IntrospectionDiagnosticsInput {
     failureCount?: number;
 }
 interface AppilotsClientOptions {
+    sessionStorage?: AppilotsSessionStorage;
     projectId: string;
     apiBaseUrl?: string;
     apiKey?: string;
@@ -381,6 +417,8 @@ interface AppilotsUser {
     identifiers?: Record<string, string>;
 }
 interface SendMessageResponse {
+    mission?: MissionView;
+    replyLocale?: SupportedAppilotsLocale;
     sessionId: string;
     message: ChatMessage;
     /** Summary message to show AFTER actions complete */
@@ -400,6 +438,7 @@ interface SendMessageStreamOptions {
     onTextDelta?: (chunk: string, fullText: string) => void;
     /** Fired once when the server announces the session id. */
     onSession?: (sessionId: string) => void;
+    onReplyLocale?: (locale: SupportedAppilotsLocale) => void;
     /** Abort mid-generation (stop button). Rejects with name='AbortError'. */
     signal?: AbortSignal;
 }
@@ -429,6 +468,10 @@ declare class RateLimitedError extends Error {
 }
 /** Runtime context sent with every user message. */
 interface SendMessageContext {
+    missionProtocol?: 1;
+    missionId?: string;
+    /** Supported device language, independent of the app/map/visible UI locale. */
+    deviceLocale?: SupportedAppilotsLocale;
     /**
      * Which client platform this observation came from — `'react-native'`,
      * `'web'`, `'android'`, `'ios'`, or any other client-defined string.
@@ -484,6 +527,11 @@ declare class AppilotsClient {
     private readonly introspectionReporter;
     private readonly user;
     private sessionId;
+    private mission;
+    private missionDispatchPaused;
+    private readonly sessionStorage;
+    private readonly sessionStorageKey;
+    private sessionLoad;
     /** Guard so identify fires at most once per client instance. */
     private identified;
     constructor(options: AppilotsClientOptions);
@@ -570,6 +618,23 @@ declare class AppilotsClient {
         isDone: boolean;
         hop: number;
     }>;
+    private acceptMission;
+    getMission(): MissionView | null;
+    pauseMissionLocally(): void;
+    missionApprovalAllowed(action: AgentAction): boolean;
+    missionScopeForAction(action: AgentAction): MissionScope | undefined;
+    claimMissionAction(action: AgentAction, context: Record<string, unknown>): Promise<{
+        allowed: boolean;
+        scope: MissionScope;
+        expiresAt: number;
+    }>;
+    controlMission(command: 'observe' | 'pause' | 'resume' | 'cancel', context: Record<string, unknown>): Promise<SendMessageResponse & {
+        isDone: boolean;
+        hop: number;
+    }>;
+    private persistSession;
+    private loadStoredSession;
+    restoreMission(): Promise<MissionView | null>;
     executeAction(actionId: string): Promise<AgentAction>;
     /**
      * Rewrite an action's type when the AI used a semantically-misclassified
@@ -685,600 +750,6 @@ declare class AppilotsClient {
     }): () => void;
 }
 
-/**
- * Snapshot types — the platform-agnostic "view model" of what the user
- * is currently seeing on screen, sent to the AI agent so it has
- * accurate visible state.
- *
- * Every platform walker (React Native fiber walk, web DOM walk, ...)
- * produces this same shape; the wire contract it feeds is
- * `agentSnapshotSchema` in `@appilots/shared`.
- */
-/**
- * How much the walker actually knows about an element's identifier.
- *
- * The observation used to say nothing here, so `btn-3` — an ordinal the
- * walker invented — read to the model exactly like `testID="submit-order"`,
- * which a developer wrote down on purpose. That is how a confident press on
- * the wrong control happens.
- *
- * - `declared`   the app named it: `testID` / `data-testid` /
- *                `accessibilityLabel` / `aria-label`. Stable across renders
- *                and across releases; safe to copy into a tool call.
- * - `derived`    folded from what the user can see — the button's own text,
- *                a `label` or `placeholder` prop. Stable as long as the copy
- *                does not change, and it changes with the app's language.
- * - `positional` nothing but an ordinal in the current snapshot. Valid for
- *                this observation only: a re-render, a scroll or an inserted
- *                sibling moves it.
- *
- * ABSENT means unknown, NOT `declared` — clients published before this field
- * existed send no provenance at all, and a missing value must never be read
- * as the most trustworthy one.
- */
-type IdentityProvenance = 'declared' | 'derived' | 'positional';
-interface InputSnapshot {
-    /** Best identifier — testID/data-testid, accessibilityLabel/aria-label, or placeholder */
-    id?: string;
-    /** How `id` was obtained. See {@link IdentityProvenance}. */
-    provenance?: IdentityProvenance;
-    /**
-     * False when the control is mounted but currently outside the window —
-     * below the fold of a ScrollView, scrolled off the top, pushed sideways
-     * by a carousel.
-     *
-     * ABSENT MEANS UNKNOWN. The old React Native architecture cannot report a
-     * synchronous window-relative rect, and no SDK published before this
-     * field existed reports one at all; reading absence as `false` would make
-     * the agent refuse to press a control the user is looking at.
-     */
-    onScreen?: boolean;
-    /** Human-readable label inferred from accessibility metadata or sibling text */
-    label?: string;
-    /** Current value (only present for controlled inputs) */
-    value?: string;
-    /** Placeholder text */
-    placeholder?: string;
-    /** Whether the input is editable */
-    editable?: boolean;
-    /** Whether the input is secure (password field) */
-    secure?: boolean;
-    /** Inferred type based on the platform's input-type metadata */
-    type?: 'text' | 'email' | 'number' | 'phone' | 'password';
-    /**
-     * True when pressing return on this field submits — RN's
-     * `onSubmitEditing`, the web's implicit form submit.
-     *
-     * On a search box, a one-field login or a chat composer this IS the
-     * submit; the screen has no button and never will. Absent means the
-     * field declares no such handler, so the form needs a button.
-     */
-    submitsOnReturn?: boolean;
-    /**
-     * The app is asking for this field before the form can be submitted.
-     *
-     * ABSENT MEANS UNKNOWN, not optional: most apps never declare it, and
-     * reading absence as "not required" would let the agent submit a form
-     * it could have known was incomplete.
-     */
-    required?: boolean;
-    /**
-     * The app is currently rejecting this field's value.
-     *
-     * This is the fact the agent used to recover by READING — the error
-     * copy next to the input ("Campo obrigatório", "Formato inválido").
-     * Carrying the fact as a boolean is what lets a redacted observation
-     * still support recovery, and it is cheaper than the sentence even
-     * when nothing is redacted.
-     *
-     * Absent means the app declares no validity state — never that the
-     * field is valid.
-     */
-    invalid?: boolean;
-    /**
-     * Whether the field currently holds anything.
-     *
-     * Deliberately its own field rather than an inference over `value`.
-     * The value belongs to the user and is the first thing a privacy
-     * policy withholds; the EXISTENCE of a value belongs to the agent and
-     * is what stops it from filling the same field twice on a later hop.
-     * Separating them is what lets the second survive without the first.
-     */
-    filled?: boolean;
-    /**
-     * This input has keyboard focus right now.
-     *
-     * Tells apart "empty because nobody typed" from "empty because the
-     * user is typing in it at this moment" — the difference between
-     * completing a form and interrupting someone mid-sentence.
-     */
-    focused?: boolean;
-    /**
-     * True when this input lives inside a currently-visible modal. When a
-     * modal is open, only inModal elements can actually receive input —
-     * everything else is behind the overlay.
-     */
-    inModal?: boolean;
-}
-interface ButtonSnapshot {
-    /** Best identifier — testID/data-testid, accessibilityLabel/aria-label, or inferred from child text */
-    id?: string;
-    /** How `id` was obtained. See {@link IdentityProvenance}. */
-    provenance?: IdentityProvenance;
-    /**
-     * False when the control is mounted but currently outside the window —
-     * below the fold of a ScrollView, scrolled off the top, pushed sideways
-     * by a carousel.
-     *
-     * ABSENT MEANS UNKNOWN. The old React Native architecture cannot report a
-     * synchronous window-relative rect, and no SDK published before this
-     * field existed reports one at all; reading absence as `false` would make
-     * the agent refuse to press a control the user is looking at.
-     */
-    onScreen?: boolean;
-    /** Human-readable label — usually the visible text inside the button */
-    label?: string;
-    /** Whether the button is disabled */
-    disabled?: boolean;
-    /**
-     * Whether this control is currently in its ON state.
-     *
-     * Covers both accessibility states that mean it, because the agent
-     * needs the same thing from either: `accessibilityState.selected`
-     * (grouped, mutually-exclusive controls — segmented controls, radio
-     * groups, each option its own pressable target) and
-     * `accessibilityState.checked` (an independent checkbox).
-     *
-     * Absent means "not on OR not observable" — the walker cannot tell a
-     * custom checkbox that declares no a11y state from an ordinary button,
-     * so absence is never proof that a box is unticked.
-     */
-    selected?: boolean;
-    /** True when this button lives inside a currently-visible modal. */
-    inModal?: boolean;
-}
-interface ToggleSnapshot {
-    /** Best identifier */
-    id?: string;
-    /** How `id` was obtained. See {@link IdentityProvenance}. */
-    provenance?: IdentityProvenance;
-    /**
-     * False when the control is mounted but currently outside the window —
-     * below the fold of a ScrollView, scrolled off the top, pushed sideways
-     * by a carousel.
-     *
-     * ABSENT MEANS UNKNOWN. The old React Native architecture cannot report a
-     * synchronous window-relative rect, and no SDK published before this
-     * field existed reports one at all; reading absence as `false` would make
-     * the agent refuse to press a control the user is looking at.
-     */
-    onScreen?: boolean;
-    /** Human-readable label */
-    label?: string;
-    /** Current on/off state */
-    value?: boolean;
-    /** True when this toggle lives inside a currently-visible modal. */
-    inModal?: boolean;
-}
-interface SliderSnapshot {
-    /** Registry id — the executable handle. */
-    id?: string;
-    /** How `id` was obtained. See {@link IdentityProvenance}. */
-    provenance?: IdentityProvenance;
-    /**
-     * False when the control is mounted but currently outside the window —
-     * below the fold of a ScrollView, scrolled off the top, pushed sideways
-     * by a carousel.
-     *
-     * ABSENT MEANS UNKNOWN. The old React Native architecture cannot report a
-     * synchronous window-relative rect, and no SDK published before this
-     * field existed reports one at all; reading absence as `false` would make
-     * the agent refuse to press a control the user is looking at.
-     */
-    onScreen?: boolean;
-    /** Human-readable label */
-    label?: string;
-    /** Current numeric value */
-    value?: number;
-    /** Lower bound the executor clamps to */
-    min?: number;
-    /** Upper bound the executor clamps to */
-    max?: number;
-    /** Step the executor snaps to (omitted = continuous) */
-    step?: number;
-    /** Whether the slider is currently disabled */
-    disabled?: boolean;
-    /** True when this slider lives inside a currently-visible modal. */
-    inModal?: boolean;
-}
-interface ListItemSnapshot {
-    /** 1-indexed position within the parent list (matches "selecione o terceiro"). */
-    index: number;
-    /**
-     * 0-based index of this row in the list's backing DATA, when known.
-     * For scrolled/virtualized lists this differs from `index`.
-     */
-    dataIndex?: number;
-    /** Framework key of the row, if present (typically the item's domain id). */
-    reactKey?: string;
-    /** Runtime key supplied by list tracking, if available. */
-    itemKey?: string;
-    /** Texts captured from this item's subtree, preserving row association. */
-    texts: string[];
-    /** Buttons inside this item — e.g. an inline "Edit" button on a row. */
-    buttons: ButtonSnapshot[];
-    /** Inputs inside this item — rare but possible (inline edit row). */
-    inputs: InputSnapshot[];
-    /** Toggles inside this item. */
-    toggles: ToggleSnapshot[];
-    /**
-     * Synthetic id assigned by the walker. Stable within a single
-     * snapshot; format `list-<L>-item-<I>` (0-indexed L, 1-indexed I).
-     * Used by tap-by-ordinal resolution in the executor.
-     */
-    syntheticId: string;
-}
-interface ListSnapshot {
-    /** 0-indexed list ordinal — multiple lists on one screen get 0, 1, 2... */
-    index: number;
-    /** Runtime list id when tracking or explicit props provide one. */
-    id?: string;
-    /** The container component/tag name as observed by the walker. */
-    containerType: string;
-    /**
-     * Source that identified this list. `'fiber'`/`'auto-tracked'` are
-     * the walker's own discovery tags (a DOM walker reports
-     * `'auto-tracked'` for app-annotated lists and omits the field for
-     * heuristically-detected ones); `'registry'` means the list came
-     * from the SDK's list registry rather than the tree walk.
-     */
-    source?: 'fiber' | 'auto-tracked' | 'registry';
-    /** Total data-set count when the list exposes it. */
-    itemCount?: number;
-    /** Number of row items captured in this snapshot. */
-    visibleItemCount?: number;
-    /** True when the list reports a refresh/loading state. */
-    refreshing?: boolean;
-    /** True when total item count is known and zero. */
-    empty?: boolean;
-    /** Human-readable label if the app supplied one. */
-    label?: string;
-    /** Items in visible order. */
-    items: ListItemSnapshot[];
-    /**
-     * Lightweight text projection of the list's FULL data set (capped),
-     * so the agent can see/search rows that virtualization keeps
-     * unmounted. Each entry: 0-based data index, stable key, short text.
-     */
-    dataPreview?: ListDataPreviewEntry[];
-    /** Current vertical scroll offset in px, when readable. */
-    scrollOffsetY?: number;
-    /** True when there is scrollable content above the viewport. */
-    canScrollUp?: boolean;
-    /** True when there is scrollable content below the viewport. */
-    canScrollDown?: boolean;
-}
-interface ListDataPreviewEntry {
-    /** 0-based index in the list's backing data. */
-    index: number;
-    /** Stable key from the item's domain id when available. */
-    key?: string;
-    /** Short human-readable projection of the item (capped length). */
-    text: string;
-}
-/**
- * A scrollable surface that is NOT a collection — a long form, a detail
- * page, a settings screen inside a `ScrollView`.
- *
- * It exists as its own concept, and not as a `ListSnapshot` with zero
- * rows, because everything the agent knows how to do with a list
- * (ordinals, totals, "select the third one") is meaningless here. The
- * only affordance is paging toward content below the fold — and without
- * it, a screen taller than the viewport ends at the fold.
- */
-interface ScrollableSnapshot {
-    /** Runtime id — the handle `scroll_list` addresses. */
-    id: string;
-    /** The container component as observed: ScrollView, ... */
-    containerType: string;
-    /** Human-readable label if the app supplied one. */
-    label?: string;
-    /** Current scroll offset in px. */
-    scrollOffsetY?: number;
-    /** True when there is content above the viewport. */
-    canScrollUp?: boolean;
-    /** True when there is content below the viewport. */
-    canScrollDown?: boolean;
-    /** True when the surface scrolls sideways rather than vertically. */
-    horizontal?: boolean;
-}
-/**
- * A platform dialog covering the screen — React Native's `Alert.alert`,
- * an action sheet, an OS permission prompt.
- *
- * It renders outside React, so no amount of tree walking finds it. It
- * has to be reported separately or the agent keeps operating the app
- * underneath a dialog that blocks every real finger.
- */
-interface NativeDialogSnapshot {
-    /** Stable for as long as this dialog is open. */
-    id: string;
-    title?: string;
-    message?: string;
-    /** The buttons the user can press. Never empty. */
-    buttons: Array<{
-        label: string;
-        style?: 'default' | 'cancel' | 'destructive';
-    }>;
-}
-interface ChoiceOptionSnapshot {
-    /** 1-indexed option position within this group. */
-    index: number;
-    /** Stable-enough id for the current snapshot/action turn. */
-    syntheticId: string;
-    /** Best target id if this option is backed by a pressable component. */
-    targetId?: string;
-    /** Human-readable option label. */
-    label?: string;
-    /** Text segments that belong to this option. */
-    texts: string[];
-    /** Whether this option appears selected. */
-    selected?: boolean;
-    /** Whether this option appears disabled. */
-    disabled?: boolean;
-}
-interface ChoiceGroupSnapshot {
-    /** 0-indexed group ordinal on the current screen. */
-    index: number;
-    /** Runtime id when known, usually inherited from a list/collection. */
-    id?: string;
-    /** Human-readable label when known. */
-    label?: string;
-    /** Source that produced this choice group. */
-    source?: 'list' | 'buttons' | 'heuristic';
-    /** Visible options in order. */
-    options: ChoiceOptionSnapshot[];
-}
-interface InteractionElementListContext {
-    listIndex?: number;
-    listId?: string;
-    listLabel?: string;
-    itemIndex?: number;
-    itemKey?: string;
-    reactKey?: string;
-    syntheticId?: string;
-}
-interface InteractionElementSnapshot {
-    /** Stable id for the current screen/content, preferred for tool calls. */
-    id: string;
-    /** Semantic UI role. */
-    role: 'option' | 'button' | 'input' | 'toggle' | 'slider' | 'listItem';
-    /** Human-readable label. */
-    label?: string;
-    /** Text segments associated with this element. */
-    texts: string[];
-    /** Actions supported by this element. */
-    actions: Array<'press' | 'focus' | 'toggle' | 'setValue'>;
-    /** Whether the element is currently disabled. */
-    disabled?: boolean;
-    /** Whether the element appears selected. */
-    selected?: boolean;
-    /** Source that produced the element. */
-    source?: 'list' | 'button' | 'input' | 'toggle' | 'slider' | 'choice';
-    /**
-     * How the underlying control's identifier was obtained. Carried up from
-     * the snapshot entry this element was derived from, so a consumer that
-     * only reads `elements` still knows what it is trusting. See
-     * {@link IdentityProvenance}.
-     */
-    provenance?: IdentityProvenance;
-    /**
-     * False when the control is mounted but currently outside the window —
-     * below the fold of a ScrollView, scrolled off the top, pushed sideways
-     * by a carousel.
-     *
-     * ABSENT MEANS UNKNOWN. The old React Native architecture cannot report a
-     * synchronous window-relative rect, and no SDK published before this
-     * field existed reports one at all; reading absence as `false` would make
-     * the agent refuse to press a control the user is looking at.
-     */
-    onScreen?: boolean;
-    /** Legacy/fallback target id, if any. */
-    targetId?: string;
-    /** Context for row/list options. */
-    listContext?: InteractionElementListContext;
-    /**
-     * True when the underlying component lives inside a currently-visible
-     * modal — the only targets actually touchable while the overlay is up.
-     */
-    inModal?: boolean;
-}
-/** Window-relative box, in the coordinate space the platform reports. */
-interface ElementRect {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-/**
- * What the CLIENT keeps about an element, which is strictly more than what
- * the model is told about it.
- *
- * The wire shape (`InteractionElementSnapshot`) is sized for a language
- * model: names, roles, state, everything it needs to decide. This one adds
- * what only the executor needs — coordinates it will never read aloud —
- * and it exists because that data was being measured and then discarded
- * for want of somewhere to put it that wasn't the wire.
- *
- * The split is the point. Anything added here is free: it never reaches
- * `agentSnapshotSchema`, never crosses the network, and never costs a
- * token. Anything added to the wire type is paid for on every observation
- * of every session, so it has to earn the model's attention.
- */
-interface InteractionElementEntry extends InteractionElementSnapshot {
-    /**
-     * Where the control was on screen when the snapshot was taken. Absent
-     * when the platform cannot measure synchronously (React Native's old
-     * architecture) or when the element came from a source with no fiber
-     * behind it.
-     */
-    rect?: ElementRect;
-}
-/**
- * What changed between the previous observation and this one.
- *
- * The client holds both snapshots; the server only ever sees one. So the
- * question the agent loop asks most often — "did the action I just took
- * do anything?" — is one the client can answer as a FACT and the server
- * can only guess at. Today it guesses: `effect: 'none'` on the turn trail
- * is derived server-side from heuristics over a single snapshot.
- *
- * Everything here is shape, never content: counts, booleans, and field
- * ids that the app declared itself. That is not an accident of design —
- * it is what lets this survive a redacted or content-free observation
- * intact, and it is why the most useful signal in the observation is also
- * the cheapest one to send.
- *
- * ABSENT vs `unchanged: true` is the load-bearing distinction, and it is
- * the same one `truncated` exists to make. Absent means there was no
- * previous observation to compare against (the first capture of a
- * mission). `unchanged: true` means we DID compare and nothing moved —
- * which is the strongest evidence there is that an action did nothing.
- */
-interface SnapshotDelta {
-    /** The active route is not the one the previous observation reported. */
-    routeChanged?: boolean;
-    /** A modal or native dialog is up now and was not before. */
-    modalOpened?: boolean;
-    /** A modal or native dialog was up before and is gone now. */
-    modalClosed?: boolean;
-    /** A loading indicator appeared. */
-    loadingStarted?: boolean;
-    /** A loading indicator that was showing is gone. */
-    loadingFinished?: boolean;
-    /** How many distinct visible texts are present now that were not before. */
-    textsAdded?: number;
-    /** How many distinct visible texts are gone. */
-    textsRemoved?: number;
-    /** Net change in mounted list rows, summed across every list. */
-    visibleRowsDelta?: number;
-    /**
-     * Net change in the lists' reported DATA totals, summed. This is the
-     * one that answers "did the record actually get created", because it
-     * moves even when virtualization keeps the new row unmounted.
-     */
-    totalRowsDelta?: number;
-    /**
-     * Fields that went from empty to filled. Declared ids only — a
-     * `derived` id is folded from visible copy, so publishing it here
-     * would smuggle content through a field that claims to carry none.
-     */
-    fieldsNewlyFilled?: string[];
-    /** Fields that went from filled to empty. Declared ids only. */
-    fieldsCleared?: string[];
-    /** Some field is reporting invalid that was not reporting it before. */
-    invalidAppeared?: boolean;
-    /**
-     * Nothing above fired: we compared two observations and the screen is
-     * structurally identical. Present only when every other field is
-     * absent, so a reader never has to check all of them to know.
-     */
-    unchanged?: boolean;
-}
-interface ScreenSnapshot {
-    /** The currently active route name, if known */
-    route: string | null;
-    /** All visible static text */
-    texts: string[];
-    /** All text inputs currently rendered (and visible) */
-    inputs: InputSnapshot[];
-    /** All button-like components */
-    buttons: ButtonSnapshot[];
-    /** All toggle components */
-    toggles: ToggleSnapshot[];
-    /** Sliders / adjustable numeric controls. */
-    sliders: SliderSnapshot[];
-    /** Whether a loading indicator is visible */
-    loading: boolean;
-    /** Whether a modal is currently open */
-    modalOpen: boolean;
-    /**
-     * A native dialog covering the screen, when the SDK could observe one.
-     *
-     * Its presence also forces `modalOpen`, because for every purpose the
-     * agent cares about it IS a modal — nothing behind it is touchable.
-     * Absence is not proof there is no dialog: an OS permission prompt or
-     * a share sheet cannot be instrumented at all.
-     */
-    nativeDialog?: NativeDialogSnapshot;
-    /**
-     * Lists detected in the visible tree. Each list's items have their
-     * own per-item texts/buttons/inputs/toggles, NOT duplicated in the
-     * flat top-level arrays — preserving the row association the flat
-     * shape destroys.
-     */
-    lists: ListSnapshot[];
-    /**
-     * Choice groups detected from visible cards/rows/chips/buttons, used
-     * for select-like flows where no text input exists.
-     */
-    choiceGroups: ChoiceGroupSnapshot[];
-    /**
-     * Scrollable surfaces that carry no rows. Absent/empty means either
-     * the screen does not scroll or the SDK could not observe that it
-     * does — never that the visible content is all the content.
-     */
-    scrollables?: ScrollableSnapshot[];
-    /**
-     * Interaction graph: visible actionable elements with stable ids,
-     * semantic roles, labels, and execution fallbacks. Agents should
-     * prefer these ids over synthetic ordinal handles.
-     */
-    elements: InteractionElementSnapshot[];
-    /**
-     * Set when the walker's output exceeded the wire contract and
-     * `clampSnapshotToWireLimits` dropped part of it (see
-     * `introspection/wireLimits.ts`). Absent means the observation is
-     * complete.
-     *
-     * The server surfaces this to the model: a screen whose text was cut
-     * at 500 entries must not be read as a screen with only 500 things on
-     * it. Without the flag a truncated observation is indistinguishable
-     * from a short one.
-     */
-    truncated?: boolean;
-    /**
-     * What moved since the previous observation. See {@link SnapshotDelta}
-     * — absent means there was nothing to compare against, which is a
-     * different statement from "nothing changed".
-     *
-     * Attached by the platform adapter rather than by the walker: the
-     * baseline has to be the last snapshot that was actually SENT, and
-     * `captureSnapshot` is also called for internal probes that never
-     * leave the device.
-     */
-    delta?: SnapshotDelta;
-    /** Diagnostic counts for debugging */
-    stats?: {
-        visitedFibers: number;
-        skippedHidden: number;
-        /**
-         * How many controls the walker could name, and how well.
-         *
-         * `WalkDetectorCounts` counts RECOGNITIONS, not emissions, so a screen
-         * whose controls were all silently dropped still reported healthy
-         * detector numbers. This is the emission side: `positional` climbing is
-         * the signal that an app needs annotating, and comparing it between a
-         * debug and a release build is the first real measurement of what
-         * minification costs the agent.
-         */
-        identity?: {
-            declared: number;
-            derived: number;
-            positional: number;
-        };
-    };
-}
 /**
  * Localized copy for escalation system messages, injected by the chat
  * surface (the machine has no i18n access — same pattern as errorPrefix).
@@ -1296,69 +767,25 @@ interface EscalationStrings {
     offer: string;
 }
 
-type TraceListener = (entries: AppilotsTraceEntry[]) => void;
-declare function recordAppilotsDebugTrace(entry: Omit<AppilotsTraceEntry, 'id'> & {
-    id?: string;
-}): void;
-declare function getAppilotsDebugTraces(): AppilotsTraceEntry[];
-declare function clearAppilotsDebugTraces(): void;
-declare function subscribeAppilotsDebugTraces(listener: TraceListener): () => void;
-
-/**
- * Human-readable labels and error messages for the action breadcrumb.
- *
- * Strings are PT-BR hardcoded for now. i18n is planned for backlog item
- * 4.1 (Personalização) — when that lands, these strings move into the
- * locale bundles.
- *
- * Two responsibilities:
- *   1. `describeAction(action)` — turns a typed AgentAction into a label
- *      that varies by lifecycle state (pending/running/done/failed).
- *   2. `humanizeError(raw, action)` — sanitises the raw error string from
- *      the executor into a short user-facing reason. Stack traces and
- *      protocol errors are collapsed into "algo deu errado" so users
- *      aren't shown technical noise.
- */
-
-type BreadcrumbState = 'pending' | 'running' | 'success' | 'failed';
-interface BreadcrumbItem {
-    /** What to render on the line. */
-    label: string;
-    /** Lifecycle state — drives icon + colour in the breadcrumb. */
-    state: BreadcrumbState;
-}
-/**
- * Map an AgentAction + its current status to a breadcrumb item ready to
- * render. The function is intentionally defensive — both the native-tools
- * and JSON-fallback code paths feed actions through here, and the JSON
- * path is loose with payload shapes, so every field access has to assume
- * `unknown`.
- */
-declare function describeAction(action: AgentAction): BreadcrumbItem;
-/**
- * Convert the executor's raw error string into a short, user-facing
- * reason that fits inside parentheses on the breadcrumb line. Returns
- * `undefined` when there's no useful information to show — caller can
- * then drop the parenthetical entirely.
- *
- * Heuristics:
- *   - Apply known-pattern rewrites (rejected, not found, network, etc.)
- *   - If the result looks technical (stack frame, HTTP status, JSON
- *     dump) or is suspiciously long, fall back to "algo deu errado".
- *   - Trim and lowercase the first letter so it reads naturally inside
- *     the parens after the action verb.
- */
-declare function humanizeError(raw: string | undefined, _action?: AgentAction): string | undefined;
-
 interface AppilotsConfig {
+    /** Persist the session handle to resume a mission after an app restart. */
+    sessionStorage?: AppilotsSessionStorage;
     /** Project ID from the Appilots dashboard */
     projectId: string;
     /** API base URL (defaults to Appilots cloud) */
     apiBaseUrl?: string;
     /** SDK API key (ak_...) for authenticating with the backend */
     apiKey?: string;
-    /** Agent permissions for this app instance */
-    permissions?: AgentPermissions;
+    /**
+     * Agent permissions for this app instance.
+     *
+     * PARTIAL: name only the flags you want to change. Every flag you
+     * omit takes its default (see `DEFAULT_AGENT_PERMISSIONS`), which is
+     * also what a config with no `permissions` key at all gets — the two
+     * used to disagree, and a `.appilotsrc` naming three of the four
+     * flags silently denied the fourth.
+     */
+    permissions?: Partial<AgentPermissions>;
     /** Enable debug logging */
     debug?: boolean;
     /**
@@ -1516,6 +943,12 @@ interface UseAppilotsNavigationReturn {
 declare function useAppilotsNavigation(): UseAppilotsNavigationReturn;
 
 interface UseAppilotsChatReturn {
+    mission?: MissionView | null;
+    pauseMission: () => Promise<void>;
+    resumeMission: () => Promise<void>;
+    cancelMission: () => Promise<void>;
+    hasStartedActing: boolean;
+    replyLocale: AppilotsLocale | null;
     messages: ChatMessage[];
     isLoading: boolean;
     loadingStatusKey: 'thinking' | 'statusAnalyzing' | 'statusWaitingApp' | 'statusAdjusting';
@@ -1536,9 +969,8 @@ interface UseAppilotsChatReturn {
     /**
      * Cancels the in-flight generation (OKR-008 KR4). Streamed partial
      * text is kept in the transcript; a no-op when nothing is in flight.
-     * Cancellation only covers the generation phase — once actions start
-     * executing on-device they run to completion (interrupting a half-done
-     * form fill would leave the app in a worse state than finishing it).
+     * Pending actions and later continuation responses are discarded; an
+     * action already dispatched on-device is allowed to finish.
      */
     cancelMessage: () => void;
     clearMessages: () => void;
@@ -1616,6 +1048,45 @@ interface UseAppilotsActionsReturn {
  */
 declare function useAppilotsActions(options?: UseAppilotsActionsOptions): UseAppilotsActionsReturn;
 
+/**
+ * What a registration hook hands back for the app to spread.
+ *
+ * The registration hooks (`useAppilotsField`, `useAppilotsTarget`,
+ * `useAppilotsToggle`, `useAppilotsSlider`) returned `void`. They put the
+ * declared id in the ComponentRegistry, where the EXECUTOR looks it up,
+ * and nothing carried that id to the rendered element — so the control
+ * ended up with two identities: the declared one, which is what the
+ * application map shows the agent, and one `walkFiber` derives from the
+ * visible label (`testID ?? accessibilityLabel`, then `labelToId`, then
+ * position).
+ *
+ * The two agree only while the label spells the id. A translated app, an
+ * icon-only control, a reworded button or a label composed at runtime
+ * breaks the coincidence, and the agent then asks for something the
+ * snapshot does not contain.
+ *
+ * Spreading the return value closes it:
+ *
+ * ```tsx
+ * <Switch {...useAppilotsToggle('pushEnabled', { value, onValueChange })} />
+ * ```
+ *
+ * Ignoring it is still valid — every existing call site keeps compiling
+ * and behaving exactly as before, which is why this is additive rather
+ * than a new required argument.
+ */
+interface AppilotsElementProps {
+    /**
+     * The declared id, published where the identity chain looks FIRST.
+     *
+     * Spread it last if the component also takes a `testID` of its own and
+     * you want yours to win; spread it first if you want the declared id
+     * to win. The SDK does not decide that for you here, because unlike
+     * the HOC path there is no way to see what else you are passing.
+     */
+    testID: string;
+}
+
 /**
  * ComponentRegistry — Central registry mapping component IDs to their
  * refs, callbacks, and metadata so the ActionExecutor can find and
@@ -1635,6 +1106,8 @@ interface FieldEntry {
     setValue: (value: string) => void;
     /** Optional: focus the input */
     focus?: () => void;
+    /** End editing after the latest render, without submitting the form. */
+    finishEditing?: () => void;
     /** Field type hint for the executor */
     fieldType?: 'text' | 'select' | 'toggle' | 'date' | 'number' | 'custom';
     /** Human-readable label */
@@ -1826,7 +1299,7 @@ interface UseAppilotsFieldOptions {
  * @param id - Unique identifier for this field (e.g. "plate", "customerName")
  * @param options - Field configuration
  */
-declare function useAppilotsField(id: string, options: UseAppilotsFieldOptions): void;
+declare function useAppilotsField(id: string, options: UseAppilotsFieldOptions): AppilotsElementProps;
 
 /**
  * useAppilotsTarget — Register a pressable UI element (button, card, link)
@@ -1845,6 +1318,7 @@ declare function useAppilotsField(id: string, options: UseAppilotsFieldOptions):
  * return <Button title="Submit" onPress={handleSubmit} />;
  * ```
  */
+
 interface UseAppilotsTargetOptions {
     /** Primary press handler */
     onPress: () => void;
@@ -1864,7 +1338,7 @@ interface UseAppilotsTargetOptions {
  * @param id - Unique identifier (e.g. "submitVehicle", "openSettings")
  * @param options - Target configuration
  */
-declare function useAppilotsTarget(id: string, options: UseAppilotsTargetOptions): void;
+declare function useAppilotsTarget(id: string, options: UseAppilotsTargetOptions): AppilotsElementProps;
 
 /**
  * useAppilotsToggle — Register a toggle/switch with the ComponentRegistry
@@ -1884,6 +1358,7 @@ declare function useAppilotsTarget(id: string, options: UseAppilotsTargetOptions
  * return <Switch value={pushEnabled} onValueChange={setPushEnabled} />;
  * ```
  */
+
 interface UseAppilotsToggleOptions {
     /** Current toggle value */
     value: boolean;
@@ -1901,7 +1376,7 @@ interface UseAppilotsToggleOptions {
  * @param id - Unique identifier (e.g. "pushNotifications", "darkMode")
  * @param options - Toggle configuration
  */
-declare function useAppilotsToggle(id: string, options: UseAppilotsToggleOptions): void;
+declare function useAppilotsToggle(id: string, options: UseAppilotsToggleOptions): AppilotsElementProps;
 
 /**
  * useAppilotsSlider — Register a slider / adjustable numeric control with
@@ -1931,6 +1406,7 @@ declare function useAppilotsToggle(id: string, options: UseAppilotsToggleOptions
  * return <MySlider value={mileage} onChange={setMileage} min={0} max={300000} />;
  * ```
  */
+
 interface UseAppilotsSliderOptions {
     /** Current slider value */
     value: number;
@@ -1954,7 +1430,7 @@ interface UseAppilotsSliderOptions {
  * @param id - Unique identifier (e.g. "quilometragem", "volume")
  * @param options - Slider configuration
  */
-declare function useAppilotsSlider(id: string, options: UseAppilotsSliderOptions): void;
+declare function useAppilotsSlider(id: string, options: UseAppilotsSliderOptions): AppilotsElementProps;
 
 interface SuggestedPrompt {
     /** Display label shown on the chip and inserted into the input on tap. */
@@ -2005,4 +1481,4 @@ interface UseSuggestedPromptsReturn {
  */
 declare function useSuggestedPrompts(options: UseSuggestedPromptsOptions): UseSuggestedPromptsReturn;
 
-export { componentRegistry as $, type AppilotsThemeTokens as A, type BreadcrumbItem as B, type ComponentRegistry as C, type ListSnapshot as D, type EscalationState as E, type FieldEntry as F, type RemotePersonalization as G, type SliderEntry as H, type InteractionElementEntry as I, type SuggestedPrompt as J, type ToggleEntry as K, type ListItemSnapshot as L, type MessageRole as M, type NavigationPayload as N, type ToggleSnapshot as O, type PartialThemeTokens as P, type UseAppilotsFieldOptions as Q, RateLimitedError as R, type ScreenSnapshot as S, type TargetEntry as T, type UIInteractionPayload as U, type UseAppilotsSliderOptions as V, type UseAppilotsTargetOptions as W, type UseAppilotsToggleOptions as X, type UseSuggestedPromptsOptions as Y, type UseSuggestedPromptsReturn as Z, clearAppilotsDebugTraces as _, type AppilotsLocale as a, createComponentRegistry as a0, defaultDarkTheme as a1, defaultLightTheme as a2, describeAction as a3, getAppilotsDebugTraces as a4, humanizeError as a5, mergeThemeTokens as a6, recordAppilotsDebugTrace as a7, subscribeAppilotsDebugTraces as a8, useAppilots as a9, useAppilotsActions as aa, useAppilotsChat as ab, useAppilotsContext as ac, useAppilotsField as ad, useAppilotsNavigation as ae, useAppilotsSlider as af, useAppilotsTarget as ag, useAppilotsToggle as ah, useSuggestedPrompts as ai, type AgentAction as b, type AgentPermissions as c, type AppilotsEvent as d, type AgentActionType as e, type AgentMessage as f, AppilotsClient as g, type AppilotsClientOptions as h, type AppilotsConfig as i, type AppilotsEventHandler as j, type AppilotsEventType as k, AppilotsProvider as l, type AppilotsProviderProps as m, type AppilotsTraceEntry as n, type AppilotsUser as o, type BreadcrumbState as p, type ButtonSnapshot as q, type ChatMessage as r, type ChoiceGroupSnapshot as s, type ChoiceOptionSnapshot as t, type ComponentEntry as u, type ComponentKind as v, type FormFillPayload as w, type InputSnapshot as x, type InteractionElementListContext as y, type InteractionElementSnapshot as z };
+export { useAppilotsTarget as $, type AppilotsTraceEntry as A, type UseAppilotsTargetOptions as B, type ComponentRegistry as C, type UseAppilotsToggleOptions as D, type EscalationState as E, type FieldEntry as F, type UseSuggestedPromptsOptions as G, type UseSuggestedPromptsReturn as H, componentRegistry as I, createComponentRegistry as J, defaultDarkTheme as K, defaultLightTheme as L, type MessageRole as M, type NavigationPayload as N, mergeThemeTokens as O, type PartialThemeTokens as P, useAppilots as Q, RateLimitedError as R, type SliderEntry as S, type TargetEntry as T, type UIInteractionPayload as U, useAppilotsActions as V, useAppilotsChat as W, useAppilotsContext as X, useAppilotsField as Y, useAppilotsNavigation as Z, useAppilotsSlider as _, type AgentAction as a, useAppilotsToggle as a0, useSuggestedPrompts as a1, type AppilotsLocale as b, type AppilotsThemeTokens as c, type AppilotsSessionStorage as d, type AgentPermissions as e, type AppilotsEvent as f, type AgentActionType as g, type AgentMessage as h, AppilotsClient as i, type AppilotsClientOptions as j, type AppilotsConfig as k, type AppilotsElementProps as l, type AppilotsEventHandler as m, type AppilotsEventType as n, AppilotsProvider as o, type AppilotsProviderProps as p, type AppilotsUser as q, type ChatMessage as r, type ComponentEntry as s, type ComponentKind as t, type FormFillPayload as u, type RemotePersonalization as v, type SuggestedPrompt as w, type ToggleEntry as x, type UseAppilotsFieldOptions as y, type UseAppilotsSliderOptions as z };