@guideai/react-native 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1091 @@
+import React from 'react';
+
+interface ToolCallResponse {
+    tool: string;
+    method: string;
+    path: string;
+    params?: Record<string, unknown>;
+    body?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    requires_confirm: boolean;
+    /**
+     * Human-readable phrase for the UI ("Retrieving site information"), supplied
+     * by the model. `describeToolCall()` derives one when it is missing — the
+     * chat UI never shows the raw tool/endpoint name.
+     */
+    label?: string | null;
+}
+interface NavigationAction {
+    url: string;
+    description?: string;
+}
+interface ToolExecutionResult {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+    error_type?: string;
+    status?: number;
+}
+interface CopilotToolDef {
+    name: string;
+    description: string;
+    method: string;
+    path: string;
+    params?: {
+        name: string;
+        in: string;
+        type: string;
+        required: boolean;
+        description?: string;
+    }[];
+    body_schema?: Record<string, unknown>;
+    risk_level: 'read' | 'write' | 'destructive';
+}
+/** A host/browser tool advertised to the planner but executed only by the SDK. */
+interface ClientToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    consequential?: boolean;
+}
+interface CopilotConfig {
+    siteId: string;
+    /** Runtime label from the SDK script; this is the assistant's visible name. */
+    assistantLabel?: string;
+    /** Host-owned rule describing which requests another assistant should handle. */
+    delegationInstruction?: string;
+    /**
+     * The analytics session this chat belongs to. Sent with each question so a
+     * repeated "how do I …" can be correlated with whether the user then got
+     * there — the question alone says something is hard, the pairing says
+     * whether anything fixed it. Carries no message content.
+     */
+    analyticsSessionId?: string;
+    /**
+     * The product-analytics bundle's own ids, read at send time because that
+     * bundle can load after the chat and rotates its session when idle. Its
+     * session is the one the visitor's events are recorded under, so it wins
+     * over analyticsSessionId when present. Ids only, never content.
+     */
+    analyticsIds?: () => {
+        session_id?: string;
+        distinct_id?: string;
+    };
+    /**
+     * What this runtime can render beyond plain answers and walkthroughs. The
+     * server only sends a richer reply (a coach run for "coach") to a client
+     * that lists it, so a runtime that cannot play one keeps getting what it can.
+     */
+    clientCapabilities?: string[];
+    memoryTtlMs?: number;
+    maxMemoryMessages?: number;
+}
+/** A published interactive demo the assistant suggests playing inline (Storylane-style). */
+interface DemoSuggestion {
+    share_token: string;
+    title: string;
+    description?: string | null;
+    /** Player URL with embed=1&autostart=1 — for in-chat iframe playback. */
+    embed_url: string;
+    /** Plain player URL — for "open in new tab". */
+    share_url: string;
+    thumbnail_url?: string | null;
+    step_count?: number;
+}
+/**
+ * One element on the visitor's page the reply rings, with a caption. Only
+ * from a turn whose skill grants `can_point`; the server checked the page
+ * snapshot listed it.
+ */
+interface PagePoint {
+    selector: string;
+    text?: string;
+    caption: string;
+}
+/** A button to a page the site has. Only from a skill with `cta_buttons`. */
+interface ChatAction {
+    label: string;
+    url: string;
+}
+/**
+ * A checkout offer from the site's payment connector (agent flow). Name, price
+ * and currency come from the site's settings, never from the model; the
+ * checkout itself is created only when the visitor presses Pay.
+ */
+interface ChatPayment {
+    item_id: string;
+    name: string;
+    /** Smallest currency unit (cents, kobo). */
+    amount_minor: number;
+    currency: string;
+    provider: 'stripe' | 'paystack' | 'flutterwave' | string;
+}
+/** One stop on a coach run: reach a screen ("go"), or work through it ("do"). */
+interface CoachMilestone {
+    title: string;
+    /**
+     * A route from the site's scanned map: the screen this stop happens on.
+     * Plans from servers before Oct 2026 may leave it null.
+     */
+    route: string | null;
+    /** The page's name in the scan ("Onboarding"): what a link to it says. */
+    page?: string | null;
+    kind: 'go' | 'do';
+    /** The task can succeed without it; the visitor may skip it. */
+    optional?: boolean;
+    /** The link the site's skill and KB agree leads to this stop's page. */
+    way?: CoachTarget | null;
+    /** This stop's controls in the skill's order, each found in the KB. */
+    targets?: CoachTarget[];
+    /** Inputs the task cannot finish without (labels), held before Done. */
+    needs?: string[];
+}
+/**
+ * One step of a site skill's flow, checked against the scanned app: the
+ * skill says it is needed, the KB says where it is.
+ */
+interface CoachTarget {
+    label: string;
+    kind: 'link' | 'control' | 'field' | 'toggle' | 'section';
+    route: string;
+    /** What the visitor does with it. */
+    action: 'go' | 'open' | 'fill' | 'choose' | 'switch';
+    /** The section or menu it sits in. */
+    under?: string;
+    /** The folded group to open first when it is hidden. */
+    reveal?: string;
+    /** For a link: the page it opens. */
+    opens?: string;
+    required?: boolean;
+    /** The scanned fingerprint, when the KB has one. */
+    fingerprint?: Record<string, unknown>;
+}
+/**
+ * A coach run: "how do I…" answered by taking the visitor to the screen and
+ * talking them through it, rather than only pointing.
+ */
+interface CoachPlan {
+    goal: string;
+    intro: string;
+    /** Asked first when the task has more than one path; options are chips. */
+    question: {
+        text: string;
+        options: string[];
+    } | null;
+    milestones: CoachMilestone[];
+    /** The page the task itself is done on — the run is never coached elsewhere. */
+    task_route?: string | null;
+    /**
+     * "site", "workspace"…: the plan wanted the visitor to switch it. They are
+     * asked once to check they are in the right one instead of switching.
+     */
+    confirm_context?: string | null;
+    /**
+     * Set when this plan is new: sent back to /chat/coach/confirm once the run
+     * finishes on the task's page, and only then shared with the next visitor.
+     */
+    proof_key?: string | null;
+    done_when: {
+        route: string | null;
+        text: string | null;
+    };
+    settings?: {
+        voice: 'off' | 'browser' | 'neural';
+        explain_options: boolean;
+        offer_help: boolean;
+        vision_per_run: number;
+    };
+    cached?: boolean;
+}
+/** Escalation signal from the AI assistant. */
+interface EscalationSignal {
+    offered: boolean;
+    reason?: 'low_confidence' | 'cannot_resolve' | 'user_requested';
+    confidence?: number;
+}
+/** Callback for reporting agent loop progress to the UI. */
+type AgentStatusCallback = (status: string) => void;
+/** One step of the plan the assistant stated before it started working. */
+interface AssistantPlanStep {
+    title: string;
+    /** Endpoint this step uses; absent when the assistant does it itself. */
+    tool?: string | null;
+    /** Set when nothing available can do this step. */
+    blocked_reason?: string | null;
+}
+interface AssistantPlan {
+    steps: AssistantPlanStep[];
+    note?: string | null;
+}
+type PlanCallback = (plan: AssistantPlan) => void;
+interface HarnessResponse {
+    mode: 'answer' | 'guide' | 'execute' | 'coach';
+    answer: string;
+    /** What the assistant said it would do, shown while it works. */
+    plan?: AssistantPlan;
+    intent?: 'delegate';
+    intentReason?: string;
+    guideSteps?: Record<string, unknown>[];
+    guideTitle?: string;
+    navigation?: NavigationAction;
+    toolResult?: ToolExecutionResult;
+    confirmationNeeded?: boolean;
+    pendingToolCall?: ToolCallResponse;
+    /** Full concurrent batch when the model requested more than one tool. */
+    pendingToolCalls?: ToolCallResponse[];
+    /** When true, the ChatManager should auto-execute the pendingToolCall (read-only action). */
+    autoExecuteToolCall?: boolean;
+    autoExecute: boolean;
+    /** Escalation signal from the AI. */
+    escalation?: EscalationSignal;
+    /** Interactive demo suggestion the chat UI can play inline. */
+    demo?: DemoSuggestion;
+    point?: PagePoint;
+    actions?: ChatAction[];
+    payment?: ChatPayment;
+    coach?: CoachPlan;
+    /** One-tap replies; a tap sends the label as the next message. */
+    quickReplies?: string[];
+}
+interface ConversationMessage {
+    id?: string;
+    role: 'user' | 'assistant';
+    content: string;
+    toolResult?: ToolExecutionResult;
+    toolCalls?: ToolCallRecord[];
+    timestamp: number;
+    /** Guide steps generated by the assistant (for walkthrough buttons). */
+    guideSteps?: Record<string, unknown>[];
+    /** Title for the guide walkthrough. */
+    guideTitle?: string;
+    /** Navigation action returned by the assistant. */
+    navigation?: NavigationAction;
+    /** Response mode (answer, guide, execute). */
+    mode?: 'answer' | 'guide' | 'execute' | 'coach';
+    /** Whether this message has a pending tool call needing confirmation. */
+    confirmationNeeded?: boolean;
+    /** The pending tool call awaiting user confirmation. */
+    pendingToolCall?: ToolCallResponse;
+    /** Escalation signal from the AI. */
+    escalation?: EscalationSignal;
+    /** Interactive demo suggestion attached to this assistant message. */
+    demo?: DemoSuggestion;
+}
+/** Record of a tool call for conversation history context. */
+interface ToolCallRecord {
+    tool: string;
+    description?: string;
+    success: boolean;
+    summary?: string;
+    /** Present when the record came from a client-executed call rather than SSE. */
+    method?: string;
+    path?: string;
+}
+/** Callback for streaming text deltas to the UI. */
+type TextDeltaCallback = (delta: string) => void;
+/** Callback for tool call lifecycle events. */
+type ToolCallEventCallback = (event: ToolCallDisplayEvent) => void;
+/** Event describing tool call progress for UI display. */
+interface ToolCallDisplayEvent {
+    type: 'start' | 'done';
+    tool: string;
+    description?: string;
+    success?: boolean;
+    summary?: string;
+}
+
+/** Shared onboarding contract. UI targets are interpreted by each platform. */
+/** One highlighted action "Show me" plays, in order, on the step's page. */
+interface OnboardingAction {
+    id: string;
+    title: string;
+    instruction: string;
+    action: 'click' | 'fill' | 'select' | 'check';
+    /** Words on the control; the page is searched for them when no fingerprint matches. */
+    target_label: string;
+    target_fingerprint: Record<string, unknown>;
+    kind: string;
+    context: string;
+}
+interface OnboardingStepState {
+    id: string;
+    title: string;
+    instruction: string;
+    required: boolean;
+    state: 'complete' | 'skipped' | 'available' | 'locked';
+    /** Complete on the person's own tick (a manual step), not on evidence. */
+    self_reported?: boolean;
+    location: {
+        surface: 'web' | 'mobile' | 'desktop' | 'other';
+        screen: string;
+        target_label: string;
+        target_fingerprint: Record<string, unknown>;
+        /** A help hint on `screen` that "Show me" plays instead of highlighting a control. */
+        hint_id?: string | null;
+    };
+    completion: {
+        type: 'event' | 'screen' | 'text_visible' | 'manual';
+        value: string;
+    };
+    actions?: OnboardingAction[];
+}
+/** The button that opens the checklist; every field falls back to the card-matching default. */
+interface OnboardingLauncher {
+    label?: string;
+    invite_label?: string;
+    complete_label?: string;
+    show_progress?: boolean;
+    shape?: 'rounded' | 'pill';
+    background_color?: string | null;
+    text_color?: string | null;
+}
+interface OnboardingAppearance {
+    template: 'classic' | 'minimal' | 'bold';
+    accent_color: string;
+    /** Optional checklist surface and text colours; missing values use the SDK theme. */
+    background_color?: string | null;
+    text_color?: string | null;
+    /** Missing means the default card; position missing means left. */
+    layout?: 'card' | 'modal' | 'side';
+    position?: 'left' | 'right';
+    launcher?: OnboardingLauncher;
+}
+interface OnboardingState {
+    id: string;
+    title: string;
+    goal: string;
+    start_mode: 'automatic' | 'ask' | 'checklist';
+    chat_policy: 'unrestricted' | 'setup_only';
+    allow_dismissal: boolean;
+    appearance?: OnboardingAppearance;
+    completed: boolean;
+    dismissed: boolean;
+    completed_required: number;
+    total_required: number;
+    /** Every step, optional ones included; a skipped optional step counts as done. Missing from older servers. */
+    completed_steps?: number;
+    total_steps?: number;
+    steps: OnboardingStepState[];
+}
+
+/** A picture drawn for an answer: a PNG to show, and the SVG it was drawn as. */
+interface HeadlessImage {
+    url: string;
+    svg: string | null;
+    alt: string;
+    width: number;
+    height: number;
+}
+
+interface PageElement {
+    tag: string;
+    text: string;
+    selector: string;
+    aria_label?: string;
+    name?: string;
+    role?: string;
+    type?: string;
+    placeholder?: string;
+    /** href attribute for anchor elements */
+    href?: string;
+    /** Current value of input/textarea/select elements */
+    value?: string;
+    /** Associated label text (from <label> or aria-labelledby) */
+    label?: string;
+    /** More descriptive form label when available. */
+    form_label?: string;
+    /** True when element exists in DOM but is not currently visible */
+    hidden?: boolean;
+    /** Describes the container: "hamburger menu", "dropdown", "sidebar", etc. */
+    container?: string;
+    /** State of the container: "collapsed", "closed", etc. */
+    containerState?: string;
+    /** Nearby descriptive text from the element's parent container. */
+    parent_text?: string;
+    /** Title of the nearest visible section heading. */
+    section_title?: string;
+    /** Source URL when the element is inside an iframe */
+    iframe_src?: string;
+}
+interface PageSectionLink {
+    text: string;
+    href: string;
+    selector: string;
+}
+interface PageSection {
+    title: string;
+    selector: string;
+    text?: string;
+    links: PageSectionLink[];
+    elements: PageElement[];
+}
+interface PageSnapshot {
+    url: string;
+    title: string;
+    page_text?: string;
+    sections?: PageSection[];
+    elements: PageElement[];
+}
+
+interface ClientToolRegistry {
+    /** Tools this host can run, in the shape the backend expects. */
+    definitions(): ClientToolDefinition[];
+    /** The same tools shaped for the copilot planner and the validator. */
+    copilotDefinitions(): CopilotToolDef[];
+    /** Whether a tool name belongs to this registry. */
+    canExecute(name: string): boolean;
+    /** Whether a specific planned call is one this registry should run. */
+    canExecuteCall(toolCall: ToolCallResponse): boolean;
+    /** Run one call. Never throws — failures come back as a result. */
+    execute(toolCall: ToolCallResponse): Promise<ToolExecutionResult>;
+    /**
+     * Run several calls, reporting each as it lands.
+     *
+     * `onComplete` fires per call so a slow one cannot hold back the others'
+     * progress in the UI.
+     */
+    executeBatch(toolCalls: ToolCallResponse[], onComplete?: (toolCall: ToolCallResponse, result: ToolExecutionResult) => void): Promise<ToolExecutionResult[]>;
+    /**
+     * Release anything the registry is holding (timers, highlights).
+     *
+     * Optional: the harness has no teardown path today, so requiring it
+     * would force every registry to implement code nothing calls.
+     */
+    destroy?(): void;
+}
+
+/**
+ * A synchronous key/value store.
+ *
+ * Synchronous on purpose: the conversation memory reads storage inside
+ * `getMessages()`, which the agent loop calls from ~20 sync places.
+ * Making reads async would push `await` through the whole loop and change
+ * its public signatures for no functional gain.
+ *
+ * Web: `localStorage` already *is* this shape.
+ * React Native: MMKV or `expo-sqlite/kv-store` (both sync). A host whose
+ * only store is AsyncStorage must hydrate a snapshot at boot and write
+ * through — the honest cost of not rewriting the loop.
+ */
+interface KVStore {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Where a host keeps credentials the copilot may read, named by the
+ * source a site configured (`localStorage`, `sessionStorage`, `cookie`),
+ * or `app` for values the host app hands over itself (declared headers).
+ *
+ * Returns null for a source this platform does not have. A mobile app has
+ * no cookie jar, and saying so plainly is better than returning an empty
+ * string that reads as "present but blank".
+ */
+interface CredentialSource {
+    read(source: string, key: string): string | null;
+    /**
+     * The signed-in user's bearer token, when the host hands it over itself.
+     *
+     * A native app keeps its token where it chooses (SecureStore,
+     * AsyncStorage), not in a store the site's dashboard can name. When this
+     * returns a token it wins over the configured storage lookup for a
+     * `bearer` toolset; null falls back to that lookup.
+     */
+    authToken?(): string | null;
+}
+
+/**
+ * Decoded text chunks arriving as the response streams.
+ *
+ * Text, not bytes, on purpose. Decoding UTF-8 incrementally is the one
+ * part of stream handling that is easy to get subtly wrong: a multi-byte
+ * character split across a chunk boundary is corrupted unless the decoder
+ * carries state between chunks. Browsers have a spec-correct
+ * `TextDecoder`; React Native's polyfills vary, and one that ignores
+ * incremental mode mangles non-ASCII text silently, at runtime, past
+ * every typecheck and test.
+ *
+ * So each platform decodes where it knows the answer, and core consumes
+ * strings. **Implementations MUST handle characters split across chunk
+ * boundaries** — that is a contract, not a hint.
+ */
+type TextStream = AsyncIterable<string>;
+/** A request, already serialized. */
+interface HttpRequest {
+    url: string;
+    /**
+     * Customer toolsets declare their own verbs — a `destructive` tool is
+     * typically a DELETE — so this cannot be narrowed to GET/POST without
+     * silently rewriting those calls.
+     */
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+    headers: Record<string, string>;
+    /** Pre-serialized body. Multipart stays platform-side; see HttpTransport. */
+    body?: string;
+    signal?: AbortSignal;
+    /**
+     * Best-effort delivery while the app is tearing down. Platforms without
+     * an equivalent ignore it — the semantics are already "may be dropped".
+     */
+    keepalive?: boolean;
+}
+/**
+ * What the agent loop actually reads off a response.
+ *
+ * Deliberately narrower than `Response`. `ok` is absent because nothing
+ * reads it and its presence invites `if (!res.ok)` to drift between
+ * platforms; `blob`/`arrayBuffer`/`redirected` are absent because they
+ * have no callers.
+ */
+interface HttpResponse {
+    readonly status: number;
+    /**
+     * Header lookup. Shaped as `{ get() }` rather than a flat record to
+     * match `Headers`, so a browser transport can forward it directly.
+     */
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    json<T = unknown>(): Promise<T>;
+    text(): Promise<string>;
+    /**
+     * Present only when this response carries a readable stream. Absent is
+     * normal and handled: the caller falls back to `json()`.
+     */
+    stream?: TextStream;
+}
+interface HttpTransport {
+    request(req: HttpRequest): Promise<HttpResponse>;
+    /**
+     * Whether this platform can deliver progressive bytes at all.
+     *
+     * Read by the agent loop to decide what to *ask the backend for*. It is
+     * a property of the transport rather than a setting, so a host cannot
+     * request streaming its platform physically cannot read — that would
+     * produce an empty answer with no error.
+     *
+     * Note both browsers and React Native can stream (fetch bodies and
+     * progressive XHR respectively), so this is true on both. It exists for
+     * the runtime that genuinely cannot.
+     */
+    readonly supportsStreaming: boolean;
+}
+
+interface CopilotApi {
+    /** JSON GET with the platform's default time budget. */
+    get<T>(path: string, timeoutMs?: number): Promise<T>;
+    /** JSON POST. Encrypts the body when the client has crypto configured. */
+    post<T>(path: string, body?: unknown, timeoutMs?: number): Promise<T>;
+    /**
+     * POST returning the response unparsed, so the caller can stream it or
+     * branch on content-type. Not time-budgeted: a stream is long-lived by
+     * design and the caller owns cancellation through `signal`.
+     */
+    postRaw(path: string, body?: unknown, signal?: AbortSignal): Promise<HttpResponse>;
+    /** Whether this platform can read a response progressively. */
+    readonly supportsStreaming: boolean;
+}
+
+/**
+ * Copilot Agent Harness — client-side orchestrator.
+ *
+ * Architecture:
+ * - Backend plans the next step and formats final answers
+ * - Backend streams progress via SSE events during the loop
+ * - SDK can execute safe read tools in the browser and continue the chain
+ * - SDK reads the stream, shows status updates, and displays the final answer
+ * - For confirmed tool calls, SDK executes the customer API request in the browser
+ *
+ * Memory persists through an injected KVStore with TTL (localStorage on
+ * the web, MMKV on mobile). Multi-tenant safe via site_id scoping.
+ */
+
+declare class CopilotHarness {
+    private api;
+    private config;
+    private memory;
+    private validator;
+    private toolExecutor;
+    private tools;
+    private readonly credentials;
+    private readonly transport;
+    private activeTools;
+    private initialized;
+    /** Told about the assistant's plan as soon as the server states one. */
+    private onPlan?;
+    private lastPlanFingerprint;
+    /** The plan in force for the message being answered. */
+    private currentPlan?;
+    /** Tool inputs the host page supplies — whatever the user has open. */
+    private toolContext?;
+    /**
+     * @param tools  How this platform actually touches the screen. Defaults to
+     *   the browser registry so every existing caller is unaffected; a mobile
+     *   runtime passes one that dispatches native effects instead. The loop
+     *   below never learns which it is holding.
+     */
+    constructor(api: CopilotApi, config: CopilotConfig, tools: ClientToolRegistry, storage: KVStore, transport: HttpTransport, credentials: CredentialSource);
+    /** Hear every turn the conversation records (typed, spoken, replies). */
+    onMessageRecorded(listener: ((message: ConversationMessage) => void) | null): void;
+    /** Initialize the harness — fetch active tools for the site. */
+    initialize(): Promise<boolean>;
+    /**
+     * Register the listener that renders the assistant's plan.
+     *
+     * Set on the harness rather than passed per message: `processMessage` is
+     * already called positionally from several places, and a plan belongs to
+     * the UI for the whole session, not to one call.
+     */
+    setPlanCallback(callback: PlanCallback | undefined): void;
+    /**
+     * Values the host page supplies for tool inputs.
+     *
+     * Sent with every turn, including chain rounds — a later round builds calls
+     * too, and dropping it there is how a chain that started on the right
+     * record finishes on the default one.
+     */
+    /** Bind to the SDK's analytics session. Carries no message content. */
+    setAnalyticsSessionId(sessionId: string): void;
+    /** Read the analytics bundle's ids on every question. Ids only. */
+    setAnalyticsIds(read: () => {
+        session_id?: string;
+        distinct_id?: string;
+    }): void;
+    setToolContext(values: Record<string, string> | undefined): void;
+    /**
+     * The app's tool inputs as the API names them. A value declared in Copilot
+     * Tools as filling other inputs (app key `course` fills `content_id`) is
+     * sent under those names too; one the app set by that name already wins.
+     */
+    private contextForTools;
+    /** Whether copilot action tools are available for this site. */
+    isEnabled(): boolean;
+    /**
+     * Process a user message through the harness.
+     *
+     * 1. Sends question + history + page context to backend /ask
+     * 2. If backend returns SSE stream (agent loop running), reads events in real-time
+     * 3. Calls onStatus callback with progress updates during the loop
+     * 4. Returns the final response when the stream completes
+     * 5. For non-tool queries, returns JSON response directly
+     */
+    processMessage(question: string, pageUrl?: string, pageSnapshot?: PageSnapshot, chatMode?: string, onStatus?: AgentStatusCallback, onTextDelta?: TextDeltaCallback, onToolCallEvent?: ToolCallEventCallback, abortSignal?: AbortSignal, userContext?: Record<string, unknown>, onboardingUserId?: string): Promise<HarnessResponse>;
+    /**
+     * Execute a confirmed tool call after user approval.
+     * Called when user clicks "Yes, do it" for write/destructive actions.
+     * Executes in the browser when possible, then formats the result with LLM.
+     */
+    executeToolCall(toolCall: ToolCallResponse, originalQuestion: string, onStatus?: AgentStatusCallback, onTextDelta?: TextDeltaCallback): Promise<HarnessResponse>;
+    /** Alias for executeToolCall. */
+    confirmAndExecute(toolCall: ToolCallResponse, originalQuestion: string): Promise<HarnessResponse>;
+    /** Get conversation history for display in chat. */
+    getConversationHistory(): ConversationMessage[];
+    /** Recent redacted context for semantic conversational follow-ups. */
+    getRecentConversationContext(count?: number): {
+        role: string;
+        content: string;
+    }[];
+    /** Persist a completed Realtime turn so voice and text share one history. */
+    recordRealtimeTurn(role: 'user' | 'assistant', content: string): void;
+    /** Check if there is existing conversation history. */
+    hasHistory(): boolean;
+    /** Clear conversation history. */
+    clearHistory(): void;
+    /**
+     * Read SSE events from the backend agent loop stream.
+     * Supports incremental text streaming, tool call display events, and cancellation.
+     * Updates status via callback and resolves with the final response.
+     */
+    private _readSSEStream;
+    /**
+     * Parse the ChatAskResponse from a streamed "done" event into HarnessResponse.
+     */
+    /**
+     * Strip tool_call artifacts from streamed text so raw JSON is never shown.
+     *
+     * Handles:
+     * - Fenced code blocks: ```tool_call\n{...}```
+     * - Bare JSON objects with a "tool" key: {"tool":"list_guides","params":{}}
+     * - Standalone mode: lines (mode: execute)
+     */
+    private _stripToolCallArtifacts;
+    private _parseStreamedResponse;
+    /**
+     * Handle a regular JSON response (non-streaming).
+     */
+    /**
+     * Surface a plan to the UI once per chain.
+     *
+     * The chain revisits the server on every round, and a mid-chain response
+     * may restate the plan. Re-announcing an identical plan would redraw it and
+     * make the assistant look like it had started over, so only a changed plan
+     * is emitted.
+     */
+    private _announcePlan;
+    private _handleJsonResponse;
+    private _continueToolChain;
+    /**
+     * Remove calls that have already been made in this chain.
+     *
+     * The model is told not to repeat itself, and mostly does not, but a long
+     * chain occasionally re-requests an endpoint it already has — which costs a
+     * request and a model round trip to learn nothing new.
+     */
+    private _dropRepeats;
+    /**
+     * Run a client-executed tool chain.
+     *
+     * Each round the model may request either one tool or a batch of
+     * independent tools. A batch is executed concurrently, so the wall-clock
+     * cost of gathering four unrelated resources is one request plus one model
+     * round trip, rather than four of each. Dependent calls still arrive one at
+     * a time — the model only batches what it can run without waiting.
+     */
+    private _runClientToolChain;
+    private hasAnyLocalTools;
+    private canExecuteTool;
+    private executeLocalTool;
+    /**
+     * An MCP tool, after the user approved it: we cannot call it — it is
+     * reached from GuideAI's network with a secret the client never holds —
+     * so the backend runs it, told who the user is by their token.
+     */
+    private executeOnServer;
+    private executeLocalToolBatch;
+    private _formatToolResult;
+    private _readFormatToolResultStream;
+    private _executePendingToolCall;
+    /**
+     * Emit a fully-buffered answer to the UI.
+     *
+     * This used to fake a typing effect by releasing one word every 12ms. The
+     * response has already arrived in full by this point, so that delay was pure
+     * added latency — a 250-word answer sat behind three seconds of animation
+     * after the data was on the client. Real streaming still arrives token by
+     * token over SSE; a buffered answer is shown as soon as we have it.
+     */
+    private _emitAnswerText;
+    private _errorResponse;
+}
+
+/**
+ * The slice of MMKV this needs. Declared structurally so `new MMKV()`
+ * satisfies it without this package depending on react-native-mmkv.
+ */
+interface SyncNativeStore {
+    getString(key: string): string | undefined;
+    set(key: string, value: string): void;
+    delete(key: string): void;
+}
+
+/** Returns the signed-in user's token, or null when signed out. May be async. */
+type AuthTokenGetter = () => string | null | undefined | Promise<string | null | undefined>;
+/**
+ * Values for the headers the site's toolset declares as supplied by the app
+ * (Copilot Tools → "Supplied by your app"). May be async. Only declared
+ * names are ever sent.
+ */
+type RequestHeadersGetter = () => Record<string, string> | null | undefined | Promise<Record<string, string> | null | undefined>;
+
+/** What a host says about one control on screen. */
+interface DeclaredElement {
+    /**
+     * Stable id, unique within the screen. Becomes the snapshot's
+     * `selector` — legitimate because the backend treats `selector` as an
+     * opaque round-trip token: it renders elements to the model as numbered
+     * [ID]s and only checks the string is specific (not the word "button").
+     */
+    id: string;
+    /** Visible text. What the model matches the user's words against. */
+    label: string;
+    /** Coarse kind, mapped to the `tag` the backend's prompt expects. */
+    kind?: 'button' | 'link' | 'input' | 'text' | 'toggle' | 'image';
+    /** Current value, for inputs. */
+    value?: string;
+    /** Accessibility label when it says more than the visible text. */
+    accessibilityLabel?: string;
+    /** Placeholder text for an empty input. */
+    placeholder?: string;
+    /** True when mounted but off-screen or collapsed. */
+    hidden?: boolean;
+    /** Heading of the group this sits in, e.g. "Sharing options". */
+    sectionTitle?: string;
+}
+/** Actions a declared element can perform, supplied by the host at registration. */
+interface ElementHandlers {
+    /** Invoked by guideai_click_element. */
+    press?: () => void | Promise<void>;
+    /** Invoked by guideai_fill_field / guideai_fill_form. */
+    setValue?: (value: string) => void | Promise<void>;
+    /** Invoked by guideai_scroll_to_element. */
+    scrollTo?: () => void | Promise<void>;
+}
+
+/** The slice of React Navigation's ref this needs. */
+interface NavigationRefLike {
+    isReady?(): boolean;
+    navigate(screen: string, params?: object): void;
+    goBack(): void;
+    canGoBack?(): boolean;
+}
+
+interface GuideAIConfig {
+    /**
+     * The site's public token, from the dashboard. The only required
+     * field: it identifies the site, and everything else about that site
+     * — its tools, knowledge base, model and prompts — is resolved
+     * server-side from it.
+     */
+    apiKey: string;
+    /** The application's stable user ID after login, if already known. */
+    visitorId?: string;
+    /**
+     * A domain registered on this site (its own domain, or one of its
+     * `domain_aliases`).
+     *
+     * Required in practice, and it cannot be fetched from the dashboard:
+     * the backend uses it to AUTHORIZE the request, so it must accompany
+     * the very first call. A native app sends no `Origin` header, so this
+     * travels as `x-guideai-request-origin`. Set it once; a mismatch is
+     * answered with 403.
+     */
+    origin?: string;
+    /**
+     * Where the GuideAI backend lives. Defaults to production; set it to test
+     * against a local or staging GuideAI (`http://localhost:8000`).
+     */
+    baseUrl?: string;
+    /**
+     * How the assistant navigates between screens — a React Navigation
+     * ref, or a getter for one. Omitted, the assistant simply does not
+     * offer navigation rather than offering it and failing.
+     */
+    navigation?: NavigationRefLike | (() => NavigationRefLike | null | undefined);
+    /**
+     * A synchronous key/value store (MMKV, or `expo-sqlite/kv-store`) for
+     * conversation history across launches. Omitted, history is kept in
+     * memory and resets on relaunch.
+     */
+    store?: SyncNativeStore;
+    /** The assistant's visible name in its own replies. */
+    assistantName?: string;
+    /**
+     * Which of the site's agents (Agent Blueprints) answers, by its key —
+     * e.g. 'tutor'. Omitted: the site's main agent.
+     */
+    agent?: string;
+    /**
+     * The signed-in user's token for the site's own API. Read before every
+     * turn; may be async (AsyncStorage, SecureStore). Return null when
+     * signed out. The assistant then calls your endpoints as that user,
+     * from the device.
+     */
+    getAuthToken?: AuthTokenGetter;
+    /**
+     * Called once when your API answers 401 to a tool call. Refresh the
+     * session and return the new token; the call is repeated with it.
+     * Omitted: getAuthToken() is asked again.
+     */
+    onAuthExpired?: AuthTokenGetter;
+    /**
+     * Values for the headers your toolset declares in Copilot Tools as
+     * "Supplied by your app" — a device id, a tenant: `async () => ({
+     * 'device-id': id })`. Read before every turn; sent only to your API,
+     * never to GuideAI, and only for declared names.
+     */
+    getRequestHeaders?: RequestHeadersGetter;
+    /**
+     * Values the app knows right now — the course open on screen: `{ course:
+     * '42' }`. Each fills the API inputs of the same name, or those the
+     * toolset declares it fills (Copilot Tools → "Supplied by your app").
+     * Change it with GuideAI.setToolContext().
+     */
+    toolContext?: Record<string, string>;
+    /**
+     * Facts about the signed-in user for the agent to pitch answers to —
+     * `{ age: 12, class: 'JSS1', country: 'Nigeria', language: 'en' }`.
+     * Sent with every turn; change it with GuideAI.setUserProfile().
+     */
+    userProfile?: GuideAIUserProfile;
+    /**
+     * Log the full conversation and every request. Development only —
+     * it prints message content to the console.
+     */
+    debug?: boolean;
+}
+/** Short facts about the user: strings, numbers, booleans or short lists of them. */
+type GuideAIUserProfile = Record<string, string | number | boolean | Array<string | number>>;
+/**
+ * Configure the assistant. Call once, at app startup.
+ *
+ * Deliberately a function rather than a provider or a module constant:
+ * `apiKey` often arrives from a remote config or an env fetch, and a
+ * constructor running at import time cannot wait for it.
+ */
+declare function configure(config: GuideAIConfig): void;
+/** Call after login so chat and the checklist use the same person. */
+declare function identify(userId: string | null): void;
+/** Replace the tool inputs the app knows now (e.g. when another course opens). */
+declare function setToolContext(values: Record<string, string> | null): void;
+/** Replace what the agent knows about the user (after login, or a profile edit). */
+declare function setUserProfile(profile: GuideAIUserProfile | null): void;
+/** Whether configure() has run. Lets a host render its own fallback. */
+declare function isConfigured(): boolean;
+/** Test seam, and for hosts that switch sites at runtime. */
+declare function reset(): void;
+declare const GuideAI: {
+    configure: typeof configure;
+    identify: typeof identify;
+    setUserProfile: typeof setUserProfile;
+    setToolContext: typeof setToolContext;
+    isConfigured: typeof isConfigured;
+    reset: typeof reset;
+};
+
+interface GuideAIScreenProps {
+    /** React Navigation screen name, e.g. "ShareForm". Used by navigate(). */
+    name: string;
+    /** Scanner route path, e.g. "/share". Used for grounding. */
+    path: string;
+    /** Human title shown to the model. Defaults to `name`. */
+    title?: string;
+    /**
+     * Whether this screen is the one currently on top.
+     *
+     * Defaults to true. React Navigation keeps previous screens MOUNTED in
+     * the stack, so without this a backgrounded screen would keep claiming
+     * to be active and the model would be told about controls the user
+     * cannot see. Hosts using React Navigation should pass
+     * `useIsFocused()`.
+     */
+    active?: boolean;
+    children: React.ReactNode;
+}
+declare function GuideAIScreen({ name, path, title, active, children, }: GuideAIScreenProps): React.ReactElement;
+
+type UseGuideAIElementOptions = Omit<DeclaredElement, 'id'> & ElementHandlers;
+/**
+ * Declare one element to the assistant.
+ *
+ * Registration is an effect, so it runs after mount and unwinds on
+ * unmount. Handlers are kept in a ref and read through a stable wrapper:
+ * without that, an inline `press={() => …}` would be a new function on
+ * every render and re-register the element on every render with it.
+ */
+declare function useGuideAIElement(id: string, options: UseGuideAIElementOptions): void;
+
+interface GuideAIMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    /** True while tokens are still arriving for this message. */
+    streaming?: boolean;
+    error?: boolean;
+    /**
+     * Follow-up suggestions to draw as chips. A tap is just
+     * `send(suggestion)`.
+     */
+    suggestions?: string[];
+    /**
+     * Pictures the agent drew. They are also in `content` as Markdown
+     * images where they belong; use this list to place them yourself.
+     */
+    images?: HeadlessImage[];
+    /**
+     * A change to the user's data waiting for their yes ("Create the
+     * course"). Draw Approve / Cancel and call `confirm(id)` or `cancel(id)`.
+     */
+    pendingAction?: {
+        label: string;
+        tool: string;
+    };
+}
+/** A recording the host made (expo-audio or any recorder) and saved to a file. */
+interface GuideAIVoiceRecording {
+    /** `file://…` URI of the finished recording. */
+    uri: string;
+    /** e.g. 'audio/m4a'. Omitted: guessed from the file extension. */
+    mimeType?: string;
+    /** BCP-47 language the user spoke, e.g. 'en-NG'. Defaults to 'en-US'. */
+    languageCode?: string;
+}
+interface GuideAIVoiceResult {
+    /** What was heard, already sent as the next message; null when nothing was. */
+    text: string | null;
+    /** Why nothing was sent, in words to show the user. */
+    error?: string;
+}
+/**
+ * Everything a custom chat UI needs, and nothing about how to draw it.
+ *
+ * A host owns two things — their design, and the text the user typed.
+ * This hook owns the rest: the conversation, the streaming, the tool
+ * calls, the transport. That split is what lets the agent be upgraded
+ * underneath a host's UI without them changing a line.
+ */
+interface UseGuideAIResult {
+    /** The conversation so far, oldest first. */
+    messages: GuideAIMessage[];
+    /**
+     * The current input text, and its setter.
+     *
+     * Managed here so a host binds it straight to their TextInput rather
+     * than reimplementing "clear on send, block while busy" — the two
+     * rules every chat UI needs and each one gets subtly wrong.
+     */
+    input: string;
+    setInput(text: string): void;
+    /**
+     * Send `input`, or an explicit string.
+     *
+     * Ignores empty text and calls made while a turn is in flight, so a
+     * host does not have to guard their send button.
+     */
+    send(question?: string): Promise<void>;
+    /** True from send() until the turn settles. Drives a disabled state. */
+    busy: boolean;
+    /** Whether `send()` would do anything right now. */
+    canSend: boolean;
+    /** Status text from the agent loop ("Thinking", "Reading cart"). */
+    status: string | null;
+    /** Re-send the last user message. Useful after a failed turn. */
+    retry(): Promise<void>;
+    /** Drop the conversation and start over. */
+    clear(): void;
+    /** Approve the message's `pendingAction`; the agent carries it out. */
+    confirm(messageId: string): Promise<void>;
+    /** Decline the message's `pendingAction`. Nothing is changed. */
+    cancel(messageId: string): void;
+    /**
+     * Push-to-talk: transcribe a recording and send it as the next message.
+     * Recording is the host's (no native module here); this uploads it.
+     */
+    sendVoice(recording: GuideAIVoiceRecording): Promise<GuideAIVoiceResult>;
+    /** True while a recording is being transcribed. */
+    transcribing: boolean;
+}
+interface UseGuideAIOptions {
+    /**
+     * Log the full conversation and every request. Defaults to whatever
+     * GuideAI.configure({ debug }) was given, so a host sets it once.
+     */
+    trace?: boolean;
+    /**
+     * The harness, for tests and for a host running two assistants at
+     * once. Omitted — the normal case — it comes from GuideAI.configure(),
+     * so a host never holds a reference to it.
+     */
+    harness?: CopilotHarness;
+}
+declare function useGuideAI(options?: UseGuideAIOptions): UseGuideAIResult;
+
+/** Reads the same durable checklist as the browser adapter. */
+declare function useOnboarding(): {
+    checklist: OnboardingState | null;
+    loading: boolean;
+    refresh: () => Promise<void>;
+    dismiss: () => Promise<void>;
+};
+
+export { GuideAI, GuideAIScreen, useGuideAI, useGuideAIElement, useOnboarding };
+export type { AuthTokenGetter, DeclaredElement, ElementHandlers, GuideAIConfig, HeadlessImage as GuideAIImage, GuideAIMessage, GuideAIScreenProps, GuideAIUserProfile, GuideAIVoiceRecording, GuideAIVoiceResult, NavigationRefLike, OnboardingState, OnboardingStepState, RequestHeadersGetter, SyncNativeStore, UseGuideAIElementOptions, UseGuideAIResult };