@appilots/web-sdk 0.2.0

package/dist/AppilotsWebRuntime-DZF26UyU.d.ts

@@ -0,0 +1,1389 @@
+/** Source facts, not an executable locator or proof of a business outcome. */
+interface ControlEvidence {
+    version: 1;
+    siteId: string;
+    component: string;
+    icons: string[];
+    handler?: string;
+    calls: string[];
+    argumentBindings: string[];
+    conditions: string[];
+    nativeConfirmation?: {
+        title?: string;
+        destructiveOption: boolean;
+    };
+}
+/** Receipt of the app callback actually invoked after user approval; not database proof. */
+interface NativeConfirmationReceipt {
+    title: string;
+    message?: string;
+    buttonLabel?: string;
+    handlerCompleted: boolean;
+}
+
+/** 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
+ * tokens (via {@link useAppilotsTheme}) rather than hardcoding values, so
+ * a developer who sets a `theme` prop or dashboard config can re-skin
+ * the whole chat without forking the SDK.
+ *
+ * BACKLOG 4.1.
+ *
+ * Adding a new token:
+ *   1. Add a field to `AppilotsThemeTokens` below.
+ *   2. Set a value in BOTH `defaultLight` and `defaultDark` (and ideally
+ *      keep them visually consistent — e.g. dark text on light bg ↔
+ *      light text on dark bg).
+ *   3. Use it in components via `useAppilotsTheme()`.
+ *   4. Mirror the field on `themeTokensSchema` in `@appilots/shared` if
+ *      it should be settable from the dashboard.
+ *
+ * Removing a token is a breaking change — bump the SDK minor.
+ */
+interface AppilotsThemeTokens {
+    /** Hex color values. The 8-digit form (#RRGGBBAA) is allowed. */
+    colors: {
+        /** Brand color — send button, FAB, header dot, links. */
+        primary: string;
+        /** Secondary brand accent — used sparingly (e.g. the human-agent/operator icon accent in message rows). */
+        secondary: string;
+        /** Page/modal background, behind the messages list. */
+        background: string;
+        /** Surface color for assistant message bubbles, input field, chips. */
+        surface: string;
+        /** Default text color (high contrast on background). */
+        text: string;
+        /** Muted text — placeholders, secondary labels, "Powered by". */
+        textSecondary: string;
+        /** 1px hairlines under header, around chips. */
+        border: string;
+        /** Success state — completed action checks in the breadcrumb (ActionBreadcrumb `success` tone). */
+        success: string;
+        /**
+         * Warning / caution state — drives the breadcrumb's `pending` tone
+         * (queued, not-yet-run actions). The default is a neutral gray, not
+         * amber, so it renders pixel-identical to the SDK's pre-4.2 hardcoded
+         * palette out of the box; set an amber/yellow here to make queued
+         * actions visually louder.
+         */
+        warning: string;
+        /** Error state — failed action rows (ActionBreadcrumb `failed` tone) and destructive badges/CTAs (confirm card, reject button). */
+        error: string;
+        /** Text color for chip/button labels (e.g. suggested prompts). */
+        buttonText: string;
+        /** Text color inside the assistant's message bubble (not the user's — that stays white on `primary`). */
+        bubbleText: string;
+        /**
+         * Text color inside the USER's message bubble (on `primary`). Optional
+         * mirror of `bubbleText` for the user side — falls back to white,
+         * matching the SDK's pre-4.2 hardcoded value, when unset.
+         */
+        userBubbleText: string;
+    };
+    typography: {
+        /** Font family applied to ALL chat text. Falls back to system. */
+        fontFamily: string;
+        fontSizeXs: number;
+        fontSizeSm: number;
+        fontSizeBase: number;
+        fontSizeLg: number;
+    };
+    radii: {
+        /** Tight corners — chips, small badges. */
+        sm: number;
+        /** Default — input field, send button, secondary buttons. */
+        md: number;
+        /** Generous — chat sheet, message bubbles. */
+        lg: number;
+    };
+    /** Optional drop-shadows (RN-shaped, applied via View style). */
+    shadows: {
+        /** Tells the developer's dark/light intent. Components don't read
+         *  this directly — they read tokens — but `mode` is forwarded so
+         *  status bar / image color choices can branch on it. */
+        appearance: 'light' | 'dark';
+    };
+}
+/**
+ * Deep-partial of the token tree — what a developer hands to the SDK
+ * via the `theme` prop or dashboard config. Every field optional;
+ * unspecified fields fall through to the default.
+ */
+type PartialThemeTokens = {
+    colors?: Partial<AppilotsThemeTokens['colors']>;
+    typography?: Partial<AppilotsThemeTokens['typography']>;
+    radii?: Partial<AppilotsThemeTokens['radii']>;
+    shadows?: Partial<AppilotsThemeTokens['shadows']>;
+};
+
+/**
+ * SDK locale code. Canonical source of truth for `AppilotsLocale` — moved
+ * here (out of the React Native-coupled `i18n/I18nProvider`) so that
+ * platform-agnostic contract types (`RemotePersonalization.defaultLocale`)
+ * don't pull in a React/React Native import just for a string union type.
+ *
+ * `@appilots/sdk`'s `i18n/I18nProvider.tsx` re-exports this type from its
+ * original public path (`@appilots/sdk`'s `./i18n` barrel) so nothing
+ * downstream of the SDK's public API changes.
+ *
+ * Adding a locale = adding a bundle file in `@appilots/sdk`'s
+ * `i18n/bundles/` AND a branch in `i18n/I18nProvider.tsx`'s `BUNDLES`
+ * map AND a variant here. BACKLOG 4.1.
+ */
+type AppilotsLocale = SupportedAppilotsLocale;
+
+/**
+ * Core types for the Appilots SDK.
+ */
+
+/**
+ * Payload of `GET /agent/personalization` — what the dev configured in
+ * the dashboard under Projects > Personalization. Fetched once on
+ * `AppilotsProvider` mount and applied by `AppilotsChat` as a fallback
+ * for any prop the dev did NOT set explicitly in code
+ * (prop > remote > SDK default).
+ *
+ * Only JSON-serializable values travel here: URLs/hex/booleans work,
+ * React nodes and local `require()` assets can only come via props.
+ * `null` means "not configured" — fall through to the next source.
+ */
+interface RemotePersonalization {
+    assistantName: string | null;
+    /** Avatar URL shown next to assistant turns. */
+    assistantAvatar: string | null;
+    /** Emoji or image URL for the empty-state badge. */
+    emptyStateIcon: string | null;
+    welcomeMessage: string | null;
+    chatTitle: string | null;
+    poweredByVisible: boolean;
+    /**
+     * Partial token tree merged onto the SDK defaults. `mode` (when set)
+     * plays the role of the `themeMode` prop.
+     */
+    theme: (PartialThemeTokens & {
+        mode?: 'auto' | 'light' | 'dark';
+    }) | null;
+    defaultLocale: AppilotsLocale | null;
+    triggerButtonColor: string | null;
+    triggerButtonImageUrl: string | null;
+}
+type MessageRole = 'user' | 'assistant' | 'system' | 'human_agent';
+interface ChatMessage {
+    id: string;
+    role: MessageRole;
+    content: string;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+type AgentActionType = 'navigate' | 'form_fill' | 'ui_interaction' | 'scroll_list' | 'confirm' | 'custom';
+interface AgentAction {
+    id: string;
+    type: AgentActionType;
+    payload: NavigationPayload | FormFillPayload | UIInteractionPayload | ScrollListPayload | Record<string, unknown>;
+    status: 'pending' | 'executing' | 'completed' | 'failed';
+    error?: string;
+    /** ID of the assistant message that triggered this action */
+    messageId?: string;
+    /**
+     * BACKLOG 2.2 — When the server flags an action as destructive,
+     * the SDK renders any preceding `confirm` action with the danger
+     * variant and expects the action to be gated by user approval.
+     */
+    destructive?: boolean;
+}
+interface NavigationPayload {
+    /** Absent only for `goBack`, which has no destination to name (#398). */
+    screenName?: string;
+    params?: Record<string, unknown>;
+    navigationAction: 'push' | 'navigate' | 'replace' | 'goBack' | 'reset';
+    /**
+     * Optional path of parent navigator route names for nested screens.
+     * E.g. ['HomeTab', 'VehiclesTab'] to reach a screen inside
+     * HomeTab → VehiclesTab → screenName.
+     *
+     * React Navigation requires nested navigation params:
+     *   nav.navigate('HomeTab', { screen: 'VehiclesTab', params: { screen: 'VehicleCreate' } })
+     *
+     * The AI model provides this based on the MCP document's navigation graph.
+     */
+    path?: string[];
+}
+interface FormFillPayload {
+    screenName: string;
+    fields: FormFieldAction[];
+    /**
+     * If true, the handler presses the screen's primary submit button
+     * after all fields are filled. The submit button is resolved via
+     * `registerScreen({ actions: [{ type: 'submit', ... }] })` first,
+     * then via the fiber tree and a label heuristic.
+     *
+     * Aligned with the `submitAfterFill` field in the LLM tool schema
+     * (`agentTools.form_fill` in ai-relay.ts).
+     */
+    submitAfterFill?: boolean;
+}
+interface FormFieldAction {
+    fieldId: string;
+    fieldType: 'text' | 'select' | 'toggle' | 'date' | 'number' | 'custom';
+    value: unknown;
+    label?: string;
+}
+interface UIInteractionPayload {
+    componentId: string;
+    /** Canonical server/LLM identifier. `componentId` is kept as SDK alias. */
+    targetId?: string;
+    action: 'press' | 'longPress' | 'toggle' | 'scroll' | 'swipe' | 'focus' | 'set_value';
+    /**
+     * Numeric value for `set_value` (sliders / adjustable controls).
+     * The handler clamps to the slider's [min, max] and snaps to its step.
+     */
+    value?: number;
+    params?: Record<string, unknown>;
+}
+/**
+ * Scroll a list/collection so virtualized off-screen rows mount and
+ * show up in the next observation. Mirrors `scrollListPayloadSchema`
+ * in @appilots/shared. At least one of the fields should be present;
+ * the handler falls back to paging one viewport down when only a
+ * listId is given.
+ */
+interface ScrollListPayload {
+    /** Runtime list id from the observation's "Lists visible" block. */
+    listId?: string;
+    /** 1-based index in the list's DATA to scroll to. */
+    toIndex?: number;
+    /** Coarse paging when no target index is known. */
+    direction?: 'up' | 'down';
+}
+interface AgentPermissions {
+    canNavigate: boolean;
+    canFillForms: boolean;
+    canInteractUI: boolean;
+    canSubmitForms: boolean;
+    allowedScreens?: string[];
+    blockedScreens?: string[];
+    allowedActions?: AgentActionType[];
+}
+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;
+    data: Record<string, unknown>;
+}
+type AppilotsEventHandler = (event: AppilotsEvent) => void;
+/**
+ * Client-side view of an open escalation. `resolved` never appears
+ * here — resolution clears the state (after surfacing a system
+ * message in the transcript).
+ */
+interface EscalationState {
+    id: string;
+    status: 'pending' | 'active';
+    /** Set once an operator claims the conversation. */
+    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
+ * validator package — which means the two must be kept in step by hand.
+ * Adding a reason to one and not the other is a typecheck failure at
+ * the SDK, not a silent wire mismatch.
+ */
+interface IntrospectionDiagnosticsInput {
+    captured: boolean;
+    failureReason?: 'sentinel-missing-internals' | 'never-mounted' | 'render-crashed' | 'names-mangled' | 'walk-recognized-nothing' | null;
+    reactVersion?: string | null;
+    failureCount?: number;
+}
+interface AppilotsClientOptions {
+    sessionStorage?: AppilotsSessionStorage;
+    projectId: string;
+    apiBaseUrl?: string;
+    apiKey?: string;
+    debug?: boolean;
+    timeout?: number;
+    headers?: Record<string, string>;
+    /**
+     * Version of the MCP doc bundled with this app build. The server
+     * compares this against the currently-active MCP doc for the
+     * project and emits a `mcp_version_mismatch` telemetry event when
+     * they differ — the canonical sign that the dev shipped an app
+     * update but forgot to regenerate/upload the MCP.
+     *
+     * Tip: import this from the MCP file the CLI generates, or read it
+     * from your app's package.json so it stays in lockstep with releases.
+     */
+    mcpVersion?: string;
+    /**
+     * Reports whether the platform binding could read the host app's UI
+     * tree. Called once per message; return `null` (or omit the option)
+     * when there is nothing to report.
+     *
+     * Only a FAILED reading is put on the wire. When introspection is
+     * dead every observation is empty but perfectly well-formed, so the
+     * server cannot tell a blind session from a user looking at empty
+     * screens — this is the only signal that distinguishes them.
+     */
+    introspectionReporter?: () => IntrospectionDiagnosticsInput | null | undefined;
+    /**
+     * The host app's version (e.g. from package.json or
+     * react-native-device-info). Sent as `X-App-Version` on every request
+     * so the server can match the compatible MCP document per app build —
+     * essential for OTA-updated fleets where multiple app versions coexist.
+     */
+    appVersion?: string;
+    /**
+     * The version of the SDK package driving this client, sent as
+     * `X-Appilots-Sdk-Version`. Each platform SDK passes its OWN published
+     * version (`@appilots/sdk`, `@appilots/web-sdk`); `@appilots/client-core`
+     * is private and never published, so its version means nothing to a
+     * customer and is only the fallback for a caller that constructs
+     * `AppilotsClient` directly.
+     *
+     * This is the server's only evidence of which SDKs are in the field,
+     * and therefore the only input to "is this field safe to tighten yet?"
+     * (issue #312). Leaving it wrong is not cosmetic: it makes the
+     * backward-compatibility promise in CLAUDE.md unverifiable.
+     */
+    sdkVersion?: string;
+    /**
+     * Who the app's current user is. `id` becomes the session's
+     * externalUserId; `name`/`identifiers` are upserted into the
+     * workspace's end-users registry (fire-and-forget identify after the
+     * session opens) so support operators see a person, not an anonymous
+     * id. Identifiers are dashboard-only — never sent to the LLM.
+     */
+    user?: AppilotsUser;
+}
+interface AppilotsUser {
+    /** The app's own user id (matches your backend). */
+    id: string;
+    name?: string;
+    /** Free-form lookup keys: { email, phone, cpf, ... }. Max 10. */
+    identifiers?: Record<string, string>;
+}
+interface SendMessageResponse {
+    mission?: MissionView;
+    replyLocale?: SupportedAppilotsLocale;
+    sessionId: string;
+    message: ChatMessage;
+    /** Summary message to show AFTER actions complete */
+    summaryMessage?: ChatMessage;
+    actions?: AgentAction[];
+    usage?: {
+        tokensUsed: number;
+        modelUsed: string;
+        latencyMs: number;
+    };
+}
+interface SendMessageStreamOptions {
+    /**
+     * Fired per SSE text-delta with the chunk and the accumulated text so
+     * far — render `fullText` directly; chunks may split words/markdown.
+     */
+    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;
+}
+/**
+ * The server refused the request because this workspace (or this end
+ * user) is going too fast — HTTP 429, `error.code = 'RATE_LIMITED'`.
+ * See `apps/api/src/common/services/relay-rate-limit.ts`.
+ *
+ * A distinct type for two reasons, both of which the plain `Error` the
+ * transport used to throw could not express:
+ *
+ *  - It is a POLICY rejection, not a transport failure. On the streaming
+ *    path that distinction decides whether the caller retries: a stream
+ *    that dies before its first event is safely retried against the
+ *    non-streaming endpoint, but retrying a 429 immediately is exactly
+ *    the behaviour the limit exists to stop, and it earns a second 429.
+ *  - It carries `retryAfterSeconds`, so a caller can say WHEN instead of
+ *    "try again later", and can back off instead of spinning.
+ *
+ * `retryAfterSeconds` is read from the response envelope, falling back
+ * to the `Retry-After` header and then to 60 — a client that waits a
+ * minute is never wrong by much, and never zero.
+ */
+declare class RateLimitedError extends Error {
+    readonly retryAfterSeconds: number;
+    constructor(message: string, retryAfterSeconds: number);
+}
+/** 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.
+     * The server treats an absent value as `'react-native'` (see
+     * `docs/agent-contract.md`'s "The `platform` field" section), so
+     * setting it is optional but forward-compatible: a client that sends
+     * it explicitly isn't relying on that default staying `'react-native'`
+     * forever.
+     */
+    platform?: string;
+    currentScreen?: string;
+    formState?: Record<string, unknown>;
+    /** Design-time screen metadata from registerScreen() or the MCP doc */
+    screenMetadata?: Record<string, unknown>;
+    /** Runtime React Navigation summary captured by the SDK */
+    navigationState?: {
+        currentRouteName?: string;
+        activePath?: string[];
+        rootRouteNames?: string[];
+        currentRouteNames?: string[];
+        routeNames?: string[];
+        canGoBack?: boolean;
+    };
+    /** Runtime snapshot from captureSnapshot() — what's actually visible */
+    snapshot?: Record<string, unknown>;
+    /** Legacy registry snapshot — kept as a fallback signal */
+    registeredComponents?: Array<{
+        id: string;
+        kind: 'field' | 'target' | 'toggle';
+        screen?: string;
+        label?: string;
+    }>;
+    /** Runtime list registry snapshot — collection metadata even when rows are virtualized. */
+    registeredLists?: Array<{
+        kind: 'list';
+        id: string;
+        component: string;
+        itemCount?: number;
+        label?: string;
+        screen?: string;
+        refreshing?: boolean;
+        empty?: boolean;
+    }>;
+}
+
+declare class AppilotsClient {
+    private readonly baseUrl;
+    private readonly projectId;
+    private readonly headers;
+    private readonly timeout;
+    private readonly debug;
+    private readonly mcpVersion;
+    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);
+    /**
+     * A 404 on an `/agent/*` path is almost never a missing record — those
+     * routes are static. It means the request reached SOMETHING that is not
+     * this API, or reached it at the wrong mount point, and the server's own
+     * message ("Route not found") tells the integrator nothing about which.
+     *
+     * The symptom is unmistakable once you have seen it: every message
+     * fails, including a plain "hello" that needs no tool at all, because
+     * nothing ever reaches the agent. Left as-is it reads like the agent is
+     * broken.
+     */
+    private explainIfMisroutedBaseUrl;
+    private log;
+    private describeNonJsonResponse;
+    private request;
+    createSession(userId?: string, deviceInfo?: Record<string, unknown>): Promise<string>;
+    /**
+     * Upsert the configured user into the end-users registry. Fires once
+     * per client, after the first session opens; fire-and-forget — a
+     * failed identify must never break the chat.
+     */
+    private identifyConfiguredUser;
+    destroySession(): Promise<void>;
+    getSessionId(): string | null;
+    /**
+     * Wire fragment for introspection health. Empty on the happy path —
+     * a working client sends nothing, so the field costs a byte only
+     * when something is actually wrong. Never throws: a broken reporter
+     * must not take the message down with it.
+     */
+    private introspectionFragment;
+    sendMessage(content: string, context?: SendMessageContext): Promise<SendMessageResponse>;
+    /**
+     * Streaming variant of `sendMessage` — consumes the server's SSE
+     * endpoint (`/agent/message/stream`) and fires `onTextDelta` per chunk
+     * so the UI can render tokens as they arrive (OKR-008 KR1). Resolves
+     * with the same `SendMessageResponse` shape once the `done` event lands.
+     *
+     * Uses XMLHttpRequest because React Native's fetch does not expose
+     * `response.body` for incremental reads; RN's XHR delivers progressive
+     * `responseText`, which is the standard SSE transport on RN.
+     *
+     * Errors:
+     * - `StreamTransportError` — transport failed before ANY event; safe
+     *   for the caller to fall back to the non-streaming endpoint.
+     * - `StreamAbortError` (name='AbortError') — options.signal fired;
+     *   carries `partialContent` so the UI can keep what streamed.
+     */
+    sendMessageStream(content: string, context?: SendMessageContext, options?: SendMessageStreamOptions): Promise<SendMessageResponse>;
+    continueAgent(results: Array<{
+        actionId: string;
+        type: string;
+        success: boolean;
+        error?: string;
+        summary?: string;
+        /** BACKLOG 3.2 — structured failure diagnose, server uses for recovery */
+        diagnose?: {
+            category: 'component-not-found' | 'disabled' | 'validation' | 'network-5xx' | 'network-4xx' | 'screen-timeout' | 'ambiguous-target' | 'unknown';
+            visibleMessage?: string;
+            fieldId?: string;
+            targetId?: string;
+            screen?: string;
+            httpStatus?: number;
+            /** Candidate ids when resolution failed due to ambiguity. */
+            candidates?: string[];
+            recoverable?: boolean;
+            requiresUserInput?: boolean;
+        };
+        /** BACKLOG 3.2 — how many times this fingerprint has been retried (1 = first retry). */
+        recoveryAttempt?: number;
+        /** BACKLOG 3.2 — set when SDK has hit the per-action retry cap. */
+        recoveryExhausted?: boolean;
+        /**
+         * Set when a handler reported success but the expected visible
+         * side-effect did not happen, e.g. navigate returned but route stayed.
+         */
+        toolWithoutEffect?: boolean;
+        effect?: 'unknown' | 'none' | 'partial' | 'changed' | 'completed';
+        userVisibleStatusKey?: string;
+    }>, context: Record<string, unknown>, hop: number): Promise<SendMessageResponse & {
+        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
+     * action type. The most common case: the LLM emits
+     *   { type: 'ui_interaction', payload: { action: 'select', targetId, value } }
+     * to mean "set this field's value", which is really a form_fill. We detect
+     * that here and convert it before normalization, so the executor sees the
+     * right action shape and the field's setValue() is called instead of a
+     * meaningless press on a non-pressable component.
+     */
+    private rewriteActionTypeIfNeeded;
+    /**
+     * Normalize API tool call payloads to match SDK's expected payload types.
+     * The AI model may return slightly different field names than what the
+     * SDK executor expects, and may use vocabulary (e.g. "select", "scroll_to",
+     * "open") that the SDK doesn't natively support — we remap those to the
+     * nearest equivalent here so the executor never sees an "unknown action".
+     */
+    private normalizePayload;
+    /**
+     * Legacy per-action status report. The agentic chat loop reports via
+     * `continueAgent` (which carries diagnose + a fresh snapshot); this
+     * endpoint remains for apps driving actions manually through
+     * `useAppilotsActions`. `diagnose` is forwarded when provided so even
+     * the legacy path gives the server a failure category.
+     */
+    completeAction(actionId: string, success: boolean, error?: string, diagnose?: Record<string, unknown>): Promise<void>;
+    /**
+     * Fetch actions the server has persisted but that haven't been
+     * completed yet. Use after an SSE drop or a hard error to recover
+     * the batch without losing the actions the model already decided.
+     *
+     * Returns an empty array if there are no pending actions or if the
+     * call fails — never throws.
+     */
+    recoverPendingActions(sessionId?: string): Promise<AgentAction[]>;
+    /**
+     * Fetch dev-defined and empirically-popular prompts to seed the chat
+     * empty-state with one-tap chips. Cheap (cached server-side for 1h) but
+     * still a network hit, so callers should debounce around chat-open.
+     *
+     * @param screen Optional — when provided, response includes screen-scoped
+     *               popular prompts in addition to globals.
+     */
+    getPopularPrompts(screen?: string, limit?: number): Promise<{
+        devDefined: string[];
+        screenPopular: string[];
+        globalPopular: string[];
+        computedAt: string;
+    }>;
+    /**
+     * Fetch the project's dashboard-configured personalization (theme,
+     * branding, FAB color/image, locale...). Called by `AppilotsProvider`
+     * once on mount — cheap (cached server-side for 1h) and applied by
+     * `AppilotsChat` as a fallback for props not set explicitly in code.
+     *
+     * Throws on network/HTTP failure — the provider treats any failure as
+     * "no remote config" and stays on props/defaults.
+     */
+    getPersonalization(): Promise<RemotePersonalization>;
+    /**
+     * Ask for a human operator. Idempotent: if the session already has
+     * an open escalation the server returns it instead of creating a
+     * duplicate. Creates the session first when the chat had none yet
+     * (the server sends it back and we adopt it, so the whole
+     * conversation stays under one sessionId).
+     */
+    requestEscalation(reason: 'user_requested' | 'agent_gave_up', note?: string): Promise<{
+        escalationId: string;
+        status: 'pending' | 'active';
+    }>;
+    /**
+     * Tell the server the user walked away from the conversation (chat
+     * cleared) so the escalation is closed instead of leaving the
+     * operator talking to nobody. Fire-and-forget: never throws — the
+     * local cleanup must proceed even if the network is gone.
+     */
+    abandonEscalation(escalationId: string): Promise<void>;
+    /** User message routed to the human operator (no LLM involved). */
+    sendEscalationMessage(escalationId: string, content: string): Promise<void>;
+    /**
+     * Poll fallback / reconnect catch-up: status + operator messages
+     * created after `since` (ISO timestamp of the last one we have).
+     */
+    getEscalationUpdates(escalationId: string, since?: string): Promise<{
+        status: 'pending' | 'active' | 'resolved';
+        messages: Array<{
+            id: string;
+            content: string;
+            createdAt: string;
+        }>;
+    }>;
+    /**
+     * Open the escalation SSE channel — operator replies + status
+     * changes pushed live. Same XHR transport as `sendMessageStream`
+     * (RN's fetch can't read a body incrementally).
+     *
+     * Long-lived by design: no idle watchdog — the server pings every
+     * 25s, and a genuinely dead connection surfaces as `onClose`, which
+     * the hook answers with a backoff reconnect + `since` catch-up.
+     * Returns a close function; closing never fires `onClose`.
+     */
+    openEscalationStream(escalationId: string, handlers: {
+        since?: string;
+        onHumanMessage: (message: {
+            id: string;
+            content: string;
+            createdAt: string;
+        }) => void;
+        onStatus: (status: 'pending' | 'active' | 'resolved', operatorName?: string) => void;
+        /** Transport ended (error or server close) — caller decides on reconnect. */
+        onClose: () => void;
+    }): () => void;
+}
+
+type ActionFailureCategory = 'component-not-found' | 'disabled' | 'validation' | 'network-5xx' | 'network-4xx' | 'screen-timeout' | 'ambiguous-target' | 'unknown';
+interface ActionDiagnose {
+    category: ActionFailureCategory;
+    visibleMessage?: string;
+    fieldId?: string;
+    targetId?: string;
+    screen?: string;
+    httpStatus?: number;
+    candidates?: string[];
+    recoverable?: boolean;
+    requiresUserInput?: boolean;
+}
+/** Effect classification an executor can attach to a result. */
+type ActionEffect = 'unknown' | 'none' | 'partial' | 'changed' | 'completed';
+/** Terminal result of executing one action locally. */
+interface ActionExecutionResult {
+    success: boolean;
+    error?: string;
+    diagnose?: ActionDiagnose;
+    effect?: ActionEffect;
+    userVisibleStatusKey?: string;
+}
+/** One entry of the `results` array POSTed to /agent/continue. */
+interface TurnActionReport {
+    nativeConfirmation?: NativeConfirmationReceipt;
+    actionId: string;
+    type: string;
+    success: boolean;
+    error?: string;
+    summary?: string;
+    diagnose?: ActionDiagnose;
+    recoveryAttempt?: number;
+    recoveryExhausted?: boolean;
+    toolWithoutEffect?: boolean;
+    effect?: ActionEffect;
+    userVisibleStatusKey?: string;
+}
+type ChatLoadingStatusKey = 'thinking' | 'statusAnalyzing' | 'statusWaitingApp' | 'statusAdjusting';
+/**
+ * Localized copy for escalation system messages, injected by the chat
+ * surface (the machine has no i18n access — same pattern as errorPrefix).
+ * When omitted, no system messages are appended but the state machine
+ * still works.
+ */
+interface EscalationStrings {
+    /** Appended right after the escalation is created. */
+    requested: string;
+    /** Appended when an operator claims the conversation. */
+    connected: string;
+    /** Appended when the operator resolves — AI takes over again. */
+    resolved: string;
+    /** Content of the offer chip message appended when the agent gives up. */
+    offer: string;
+}
+interface ChatSessionOptions {
+    /** User-facing prefix for client-side failures before the relay can answer. */
+    errorPrefix?: string;
+    /**
+     * Stream assistant replies token-by-token via SSE (default true).
+     * When the streaming transport fails before any output, the machine
+     * falls back to the non-streaming endpoint transparently.
+     */
+    streaming?: boolean;
+    /** Localized escalation copy — see EscalationStrings. */
+    escalationStrings?: EscalationStrings;
+}
+interface ChatSessionState {
+    mission?: MissionView | null;
+    /** Current request has dispatched an app action; retained across continuation hops. */
+    hasStartedActing: boolean;
+    replyLocale: AppilotsLocale | null;
+    messages: ChatMessage[];
+    isLoading: boolean;
+    loadingStatusKey: ChatLoadingStatusKey;
+    error: string | null;
+    pendingActions: AgentAction[];
+    /**
+     * Open escalation, or null. While set, `sendMessage` routes to the
+     * human channel — the agent session itself is never interrupted.
+     */
+    escalation: EscalationState | null;
+}
+/** Everything the chat machine needs from the transport client. */
+interface ChatSessionClient {
+    restoreMission?(): Promise<MissionView | null>;
+    getMission?(): MissionView | null;
+    pauseMissionLocally?(): void;
+    controlMission?(command: 'observe' | 'pause' | 'resume' | 'cancel', context: Record<string, unknown>): Promise<SendMessageResponse & {
+        isDone: boolean;
+        hop: number;
+    }>;
+    sendMessage(content: string, context?: SendMessageContext): Promise<SendMessageResponse>;
+    sendMessageStream(content: string, context?: SendMessageContext, options?: SendMessageStreamOptions): Promise<SendMessageResponse>;
+    continueAgent(results: TurnActionReport[], context: Record<string, unknown>, hop: number): Promise<SendMessageResponse & {
+        isDone: boolean;
+        hop: number;
+    }>;
+    requestEscalation(reason: 'user_requested' | 'agent_gave_up', note?: string): Promise<{
+        escalationId: string;
+        status: 'pending' | 'active';
+    }>;
+    abandonEscalation(escalationId: string): Promise<void>;
+    sendEscalationMessage(escalationId: string, content: string): Promise<void>;
+    openEscalationStream(escalationId: string, handlers: {
+        since?: string;
+        onHumanMessage: (message: {
+            id: string;
+            content: string;
+            createdAt: string;
+        }) => void;
+        onStatus: (status: 'pending' | 'active' | 'resolved', operatorName?: string) => void;
+        onClose: () => void;
+    }): () => void;
+    destroySession(): Promise<void> | void;
+}
+/** Input handed to the platform adapter after a turn's actions finished. */
+interface SettleTurnInput {
+    /** Whether any action in this turn was a navigate. */
+    hadNavigate: boolean;
+    /** Screen observed when the turn started, BEFORE any navigate dispatched. */
+    preNavigateScreen: string | null;
+    /** Full route signature (name + params) captured pre-navigate. */
+    preNavigateSignature: string | null;
+    /** The turn's actions, in order. */
+    turnActions: AgentAction[];
+    /**
+     * Terminal execution results reported so far (actionId → outcome).
+     *
+     * `effect` é o veredito POR AÇÃO, medido com baseline tirado antes do
+     * press. Quem consome este input não pode contradizê-lo: a verificação
+     * de turno roda depois de tudo executado, então o baseline dela é
+     * estruturalmente posterior ao efeito que ela tenta observar.
+     */
+    results: Array<{
+        actionId: string;
+        type: string;
+        success: boolean;
+        effect?: ActionEffect;
+    }>;
+    /** componentId of the most recent press-like ui_interaction, if any. */
+    pressedComponentId: string | null;
+    /** screenName of the most recent navigate action, if any. */
+    navigateTargetScreen: string | null;
+}
+interface SettleTurnOutcome {
+    /** True when the platform gave up waiting for async work to finish. */
+    loadingPending: boolean;
+    /** Action ids that "succeeded" but produced no observable effect. */
+    toolWithoutEffectIds: Set<string>;
+}
+/**
+ * The imperative platform surface the chat machine calls into. React
+ * Native implements this with the fiber walker + React Navigation
+ * settling; web implements it with a DOM walker + history/router.
+ */
+interface ChatPlatformAdapter {
+    /**
+     * Build the rich runtime context that travels with every agent turn:
+     * platform id, route name, screen metadata, UI snapshot, registries.
+     */
+    buildContext(extras?: {
+        loadingPending?: boolean;
+        /**
+         * This is the first observation of a NEW user request, so any
+         * cross-observation state the adapter keeps — today the baseline for
+         * `snapshot.delta` — starts over. Without it the first hop of a
+         * mission would report whatever the person did on their own since
+         * the last one as the effect of the agent's previous action.
+         */
+        newMission?: boolean;
+    }): Record<string, unknown>;
+    /** Current route name, or null when unknown. */
+    getCurrentScreen(): string | null;
+    /** Full route+params signature, or null when unknown. */
+    getCurrentScreenSignature(): string | null;
+    /**
+     * Wait for the UI to settle after a turn's actions executed, and
+     * detect actions that reported success but had no observable effect.
+     * Runs BEFORE the fresh context is captured.
+     */
+    settleTurn(input: SettleTurnInput): Promise<SettleTurnOutcome>;
+}
+interface ChatSessionMachineDeps {
+    client: ChatSessionClient;
+    adapter: ChatPlatformAdapter;
+    emit: (event: AppilotsEvent) => void;
+    /** Debug warn sink — defaults to console.warn. */
+    warn?: (message: string, ...args: unknown[]) => void;
+}
+/**
+ * Loose structural view of one declared screen action's metadata
+ * (mirrors the SDK's ScreenActionMetadata without importing it).
+ */
+interface ScreenActionMetadataLike {
+    id: string;
+    label?: string;
+    requiresConfirmation?: boolean;
+    [key: string]: unknown;
+}
+/** Everything the action queue machine needs from the transport client. */
+interface ActionQueueClient {
+    missionApprovalAllowed?(action: AgentAction): boolean;
+    missionScopeForAction?(action: AgentAction): MissionScope | undefined;
+    claimMissionAction?(action: AgentAction, context: Record<string, unknown>): Promise<{
+        allowed: boolean;
+        scope: MissionScope;
+        expiresAt: number;
+    }>;
+    completeAction(actionId: string, success: boolean, error?: string, diagnose?: Record<string, unknown>): Promise<void>;
+}
+/**
+ * The imperative platform surface the action queue calls into: actually
+ * executing an action against the live UI, plus the navigation probes
+ * used to sequence post-navigate actions.
+ */
+interface ActionRunnerAdapter {
+    /** Fresh platform evidence for mission scope validation, before and after dispatch claims. */
+    buildMissionContext?(): Record<string, unknown>;
+    /**
+     * Execute one action against the platform UI. `confirmedDestructive`
+     * is true when a destructive confirm gating this action was already
+     * approved by the user — platforms use it to suppress their own
+     * native re-confirmation dialog (RN monkey-patches Alert.alert; web
+     * patches window.confirm).
+     */
+    execute(action: AgentAction, options: {
+        confirmedDestructive: boolean;
+    }): Promise<ActionExecutionResult>;
+    getCurrentScreen(): string | null;
+    getCurrentScreenSignature(): string | null;
+    /** Declared action metadata for a screen, if the app registered any. */
+    getScreenActionsMetadata(screen: string): Array<ScreenActionMetadataLike | string> | undefined;
+    /** Wait for a navigate to land before executing subsequent actions. */
+    waitForScreenSettle(options: {
+        expectingChange: boolean;
+        fromScreen: string | null;
+        fromSignature: string | null;
+        maxMs: number;
+    }): Promise<{
+        screen: string | null;
+        transitioned: boolean;
+        timedOut: boolean;
+        waitedMs: number;
+    }>;
+}
+interface ActionQueueMachineDeps {
+    client: ActionQueueClient;
+    adapter: ActionRunnerAdapter;
+    emit: (event: AppilotsEvent) => void;
+    warn?: (message: string, ...args: unknown[]) => void;
+}
+interface ActionQueueState {
+    actions: AgentAction[];
+}
+
+/**
+ * ChatSessionMachine — the platform-agnostic chat/turn/continuation
+ * state machine extracted from the RN `useAppilotsChat` hook.
+ *
+ * It owns: the message transcript, the pending-action list for the
+ * current turn, loading/error state, per-turn result bookkeeping, the
+ * recovery-attempt counters, the /agent/continue loop, and the human-
+ * escalation channel. Platforms plug in through `ChatPlatformAdapter`
+ * (context capture + post-action settling) and forward the shared
+ * event bus into `handleEvent`.
+ */
+
+declare class ChatSessionMachine {
+    private readonly deps;
+    private options;
+    private state;
+    private readonly listeners;
+    private messageIdCounter;
+    private generation;
+    private currentTurn;
+    private continuationInFlight;
+    private deviceLocale;
+    private missionSuspended;
+    /**
+     * BACKLOG 3.2 — per-message-thread retry counter, keyed on action
+     * fingerprint. Reset on every fresh `sendMessage`, persists across
+     * /agent/continue hops within the same user turn so two retries of
+     * the same action add up across hops.
+     */
+    private recoveryCountByFingerprint;
+    /** Abort controller for the in-flight generation (cancelMessage). */
+    private abortController;
+    private escalationStreamClose;
+    private escalationReconnectAttempt;
+    private escalationReconnectTimer;
+    /** createdAt of the newest operator message — reconnect catch-up cursor. */
+    private escalationSince;
+    /** Operator message ids already appended (SSE replay dedupe). */
+    private seenHumanMessageIds;
+    private disposed;
+    constructor(deps: ChatSessionMachineDeps, options?: ChatSessionOptions);
+    getState(): ChatSessionState;
+    subscribeState(listener: () => void): () => void;
+    /** Update mutable options (errorPrefix, streaming, escalation copy). */
+    setOptions(options: ChatSessionOptions): void;
+    /** Tear down timers and the escalation stream. Safe to call twice. */
+    dispose(): void;
+    private setState;
+    private warn;
+    private addAssistantMessage;
+    private addMissionReply;
+    private appendLocalSystemMessage;
+    requestHuman(reason?: 'user_requested' | 'agent_gave_up'): Promise<void>;
+    /**
+     * Live channel: operator replies + status changes. Reopens with
+     * capped exponential backoff (and a `since` catch-up cursor) when
+     * the transport drops, for as long as the escalation stays open.
+     */
+    private openEscalationStream;
+    private closeEscalationStream;
+    /** Route a user message to the human channel while escalated. */
+    private sendEscalationMessage;
+    private beginTurn;
+    private registerSynthesizedTurnAction;
+    private runContinuation;
+    handleEvent(event: AppilotsEvent): void;
+    sendMessage(content: string): Promise<void>;
+    /** Stop future work, keeping partial text and allowing an already dispatched action to settle. */
+    cancelMessage(): void;
+    restoreMission(): Promise<void>;
+    pauseMission(): Promise<void>;
+    resumeMission(): Promise<void>;
+    cancelMission(): Promise<void>;
+    private controlMission;
+    clearMessages(): void;
+    clearError(): void;
+}
+
+/**
+ * ActionQueueMachine — the platform-agnostic action queue extracted
+ * from the RN `useAppilotsActions` hook.
+ *
+ * It owns: the action list and its status transitions, sequential
+ * auto-execution, the confirm gate (server-injected and locally
+ * synthesized), backend result reporting, and approve/reject. The
+ * platform supplies actual execution and the navigation probes through
+ * `ActionRunnerAdapter`.
+ */
+
+interface ActionQueueOptions {
+    /**
+     * If true, actions are executed automatically without user approval.
+     * Confirm actions always require approval regardless of this setting.
+     * @default false
+     */
+    autoExecute?: boolean;
+}
+declare class ActionQueueMachine {
+    private readonly deps;
+    private options;
+    private state;
+    private readonly listeners;
+    /** Action ids already dispatched — never auto-executed twice. */
+    private readonly processed;
+    /** Guards against overlapping sequential runs. */
+    private draining;
+    private disposed;
+    /** Set when new work arrives while a drain is in flight. */
+    private drainRequested;
+    /** Set while a drain is queued on the microtask queue. */
+    private drainScheduled;
+    constructor(deps: ActionQueueMachineDeps, options?: ActionQueueOptions);
+    dispose(): void;
+    getState(): ActionQueueState;
+    subscribeState(listener: () => void): () => void;
+    setOptions(options: ActionQueueOptions): void;
+    private setActions;
+    private updateActions;
+    private warn;
+    handleEvent(event: AppilotsEvent): void;
+    /**
+     * Kick the sequential executor. Safe to call at any time — it
+     * coalesces while a drain is already running so a burst of arriving
+     * actions produces exactly one in-order pass.
+     *
+     * The drain is deferred to a microtask, and that is load-bearing, not
+     * a nicety. A turn's actions arrive as a synchronous burst of
+     * `agent:action:start` events, and a confirm gating a destructive
+     * action can arrive AFTER the action it protects. Draining
+     * synchronously on the first event would execute that action while
+     * its gate is still in flight — a delete running before the user
+     * confirmed it. Deferring lets the whole burst land first, so the
+     * gate is visible by the time anything executes. (The React hook this
+     * was extracted from got the same guarantee for free, from state
+     * batching before its effect ran.)
+     */
+    scheduleDrain(): void;
+    private drain;
+    /**
+     * Client-side defense-in-depth confirm injection.
+     *
+     * When the server's permission filter MISSES a destructive action
+     * (e.g. the MCP doc is stale and doesn't have the destructive flag
+     * for that action, but the live screen metadata DOES have
+     * `requiresConfirmation: true`), the action would otherwise execute
+     * immediately with no user confirmation — exactly the "delete
+     * executed before I confirmed" bug.
+     *
+     * Returns `true` when the target must NOT execute this pass (either
+     * a synthetic confirm was injected, or one is already gating it).
+     */
+    private ensureLocalConfirmIfNeeded;
+    /**
+     * Execute pending actions in order so chained actions (e.g.
+     * form_fill → press button) run in the correct sequence.
+     */
+    private executeSequentially;
+    /**
+     * A turn is an all-terminal contract: ChatSessionMachine cannot ask the
+     * server for the next step until every action in the current batch has
+     * reported a completion or an error. When an early action fails we must
+     * not execute dependent actions, but leaving them `pending` deadlocks the
+     * whole turn. Mark the untouched suffix as failed/skipped and emit the
+     * same terminal event a real executor would have emitted.
+     */
+    private skipRemainingBatchActions;
+    approveAction(actionId: string): Promise<boolean>;
+    rejectAction(actionId: string): Promise<void>;
+    get pendingActions(): AgentAction[];
+    get executingActions(): AgentAction[];
+    get completedActions(): AgentAction[];
+}
+
+/**
+ * Navigation adapter — the web answer to React Navigation.
+ *
+ * On the web there is no navigator object to interrogate, so the URL is
+ * the source of truth: the path maps to a route name and its segments
+ * to the `activePath` the agent contract expects. An app with a router
+ * (React Router, TanStack Router, ...) can inject its own `navigate()`
+ * and route table so navigation stays client-side and route names match
+ * the MCP document; without one, the adapter falls back to
+ * `history.pushState` and derives names from path segments.
+ */
+interface WebNavigationState {
+    currentRouteName?: string;
+    activePath: string[];
+    rootRouteNames: string[];
+    currentRouteNames: string[];
+    routeNames: string[];
+    canGoBack?: boolean;
+    /**
+     * Screens this session has been on, oldest first. No `backStack`
+     * counterpart: the browser exposes `history.length` and nothing about
+     * its entries, so where back goes is unknowable here.
+     */
+    visited?: string[];
+}
+/** A route the app declared, mapping an agent-facing name to a path. */
+interface WebRoute {
+    /** Route name as it appears in the MCP document (e.g. `VehicleList`). */
+    name: string;
+    /** URL path, optionally with `:param` segments (e.g. `/vehicles/:id`). */
+    path: string;
+}
+interface WebNavigationAdapterOptions {
+    /** Declared routes — the same names the MCP document uses. */
+    routes?: WebRoute[];
+    /**
+     * The app's own navigation function. Injected by a router integration
+     * so navigating stays client-side (no full page reload).
+     */
+    navigate?: (path: string, options?: {
+        replace?: boolean;
+    }) => void;
+    /** Overrides `window` — used by tests and non-browser hosts. */
+    window?: Window;
+}
+/**
+ * Match a declared route pattern against a concrete path, returning the
+ * captured params. `/vehicles/:id` vs `/vehicles/42` → `{ id: '42' }`.
+ */
+declare function matchRoute(pattern: string, pathname: string): Record<string, string> | undefined;
+/** Fill `/vehicles/:id` with `{ id: 42 }` → `/vehicles/42`. */
+declare function buildPath(pattern: string, params?: Record<string, unknown>): string;
+declare class WebNavigationAdapter {
+    private routes;
+    private navigateFn?;
+    private readonly win?;
+    /** Bumped on every navigation so the settle loop can detect movement. */
+    private listeners;
+    constructor(options?: WebNavigationAdapterOptions);
+    /** Register (or replace) the app's routes and navigate function. */
+    configure(options: Pick<WebNavigationAdapterOptions, 'routes' | 'navigate'>): void;
+    private get location();
+    /**
+     * The declared route matching the current URL, if any.
+     *
+     * When several patterns match, the most specific wins: a route with
+     * fewer `:param` segments beats one with more. Without this,
+     * declaration order decides, and `/vehicles/:id` would swallow
+     * `/vehicles/new` — resolving the create screen to VehicleDetails
+     * with `id: 'new'`.
+     */
+    private currentRoute;
+    /**
+     * Current route name: the declared route's name when the URL matches
+     * one, else a name derived from the last path segment ('/' → 'Home').
+     */
+    /**
+     * Screens this session has been on, oldest first.
+     *
+     * Recorded in `getCurrentScreen` rather than on a router event: the
+     * adapter derives the route from the URL on demand and has no state
+     * change to hook, and this method is called on every observation and
+     * throughout settle polling, so a route that is up long enough to act
+     * on is a route this sees.
+     *
+     * There is no web counterpart to `backStack`. The browser exposes
+     * `history.length` and nothing else about its entries, so where back
+     * goes is genuinely unknowable here — and the field stays absent
+     * rather than guessed.
+     */
+    private visited;
+    /** The visit log, oldest first. */
+    getVisitedScreens(): string[];
+    private recordVisit;
+    getCurrentScreen(): string | null;
+    private resolveCurrentScreen;
+    /**
+     * Route name plus its params — lets the settle loop detect a navigate
+     * to the same route with different params (`/vehicles/41` →
+     * `/vehicles/42`), which a name-only comparison would miss.
+     */
+    getCurrentScreenSignature(): string | null;
+    /**
+     * The `navigationState` block of the agent context. `activePath` is
+     * the URL's segments mapped to route names — the web equivalent of a
+     * nested navigator's active route chain.
+     */
+    getNavigationState(): WebNavigationState | null;
+    /** Path for a route name, or undefined when it is not declared. */
+    resolvePath(screenName: string, params?: Record<string, unknown>): string | undefined;
+    /** True when the app declared this route name. */
+    hasRoute(screenName: string): boolean;
+    knownRouteNames(): string[];
+    /**
+     * Navigate to a path. Uses the app's own navigate function when one
+     * was injected (keeping SPA routing intact); otherwise pushes onto
+     * the History API and notifies listeners, so a router listening to
+     * `popstate` still re-renders.
+     */
+    navigate(path: string, options?: {
+        replace?: boolean;
+    }): void;
+    goBack(): void;
+    canGoBack(): boolean;
+    subscribe(listener: () => void): () => void;
+    private notify;
+}
+
+/**
+ * AppilotsWebRuntime — wires the shared session machines to the web.
+ *
+ * This is the whole web client in one object: the transport, the two
+ * client-core state machines, and the two platform adapters that give
+ * them eyes (DOM snapshot) and hands (DOM dispatch). A React binding
+ * sits on top of it, but nothing here needs React — a Vue or vanilla
+ * app can use this class directly.
+ */
+
+/** Design-time metadata an app declares for a screen. */
+interface WebScreenMetadata {
+    name: string;
+    title?: string;
+    description?: string;
+    fields?: Array<Record<string, unknown>>;
+    actions?: Array<ScreenActionMetadataLike | string>;
+}
+interface AppilotsWebRuntimeOptions {
+    projectId: string;
+    apiKey?: string;
+    apiBaseUrl?: string;
+    debug?: boolean;
+    appVersion?: string;
+    mcpVersion?: string;
+    user?: {
+        id: string;
+        name?: string;
+        identifiers?: Record<string, string>;
+    };
+    permissions?: Partial<AgentPermissions>;
+    /** Declared routes — names must match the MCP document. */
+    routes?: WebRoute[];
+    /** The app's router navigate function, when it has one. */
+    navigate?: WebNavigationAdapterOptions['navigate'];
+    /** Screen metadata keyed by route name. */
+    screens?: WebScreenMetadata[];
+    /** Subtree to observe and act within. Defaults to the document. */
+    root?: Element;
+    /** Execute actions as they arrive, without per-action approval. */
+    autoExecute?: boolean;
+    /** Injected transport, for tests. */
+    client?: AppilotsClient;
+    chat?: ChatSessionOptions;
+}
+declare class AppilotsWebRuntime {
+    readonly client: AppilotsClient;
+    readonly navigation: WebNavigationAdapter;
+    readonly chat: ChatSessionMachine;
+    readonly actions: ActionQueueMachine;
+    /**
+     * Baseline for `snapshot.delta`. Per-runtime rather than per-module so
+     * two runtimes on one page (a preview inside an app) cannot read each
+     * other's previous screen.
+     */
+    private readonly deltaTracker;
+    private readonly handlers;
+    private readonly screens;
+    private permissions?;
+    private root?;
+    private lifetime;
+    constructor(options: AppilotsWebRuntimeOptions);
+    subscribe(handler: AppilotsEventHandler): () => void;
+    emit(event: AppilotsEvent): void;
+    configureNavigation(options: Pick<WebNavigationAdapterOptions, 'routes' | 'navigate'>): void;
+    registerScreen(metadata: WebScreenMetadata): void;
+    setPermissions(permissions: Partial<AgentPermissions> | undefined): void;
+    setRoot(root: Element | undefined): void;
+    suspend(): void;
+    resume(): void;
+    dispose(): void;
+    /**
+     * The observation sent with every turn. `platform: 'web'` is explicit
+     * on every request (including /agent/continue, which reuses this) so
+     * the server applies its platform-neutral profile rather than the
+     * React Native heuristics.
+     */
+    buildContext(extras?: {
+        loadingPending?: boolean;
+        newMission?: boolean;
+    }): Record<string, unknown>;
+    private createChatAdapter;
+    private createActionRunner;
+    /**
+     * The declared actions for a screen, expanded with one entry per live
+     * DOM element that points at a declaration via `data-appilots-action`.
+     *
+     * A list renders one delete button per row, each needing its own id to
+     * be targetable, but all of them are the same declared action and must
+     * inherit its `requiresConfirmation`. The confirm matcher is exact by
+     * design (a fuzzy one fired destructive dialogs on plain navigation),
+     * so we expand the declaration to the concrete ids instead of
+     * loosening the match.
+     */
+    private screenActionsFor;
+}
+
+export { type AgentAction as A, type ControlEvidence as C, type EscalationState as E, RateLimitedError as R, type ScreenActionMetadataLike as S, WebNavigationAdapter as W, type AppilotsLocale as a, type AgentPermissions as b, type AppilotsEvent as c, type ActionExecutionResult as d, type ActionDiagnose as e, ActionQueueMachine as f, type AgentActionType as g, AppilotsClient as h, type AppilotsEventHandler as i, AppilotsWebRuntime as j, type AppilotsWebRuntimeOptions as k, type ChatMessage as l, ChatSessionMachine as m, type ChatSessionOptions as n, type ChatSessionState as o, type EscalationStrings as p, type WebNavigationAdapterOptions as q, type WebNavigationState as r, type WebRoute as s, type WebScreenMetadata as t, buildPath as u, matchRoute as v };