@waniwani/sdk 0.11.10 → 0.11.12

package/dist/mcp/index.d.ts

@@ -1,285 +1,237 @@
-import { ContentBlock, CallToolResult, ServerRequest, ServerNotification } from '@modelcontextprotocol/sdk/types.js';
 import { ZodRawShapeCompat, ShapeOutput } from '@modelcontextprotocol/sdk/server/zod-compat.js';
 export { ZodRawShapeCompat } from '@modelcontextprotocol/sdk/server/zod-compat.js';
 import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import { ServerRequest, ServerNotification, CallToolResult, ContentBlock } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { McpServer, ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
+interface SearchResult {
+    source: string;
+    heading: string;
+    content: string;
+    score: number;
+    metadata?: Record<string, string>;
+}
+/** A file to ingest into the knowledge base */
+interface KbIngestFile {
+    /** Filename (used as chunk source identifier) */
+    filename: string;
+    /** Markdown content of the file */
+    content: string;
+    /** Arbitrary key-value metadata attached to all chunks from this file */
+    metadata?: Record<string, string>;
+}
+/** Response from the ingest endpoint */
+interface KbIngestResult {
+    /** Number of chunks created from the ingested files */
+    chunksIngested: number;
+    /** Number of files successfully processed */
+    filesProcessed: number;
+}
+/** Options for the search method */
+interface KbSearchOptions {
+    /** Number of results to return (1-20, default 5) */
+    topK?: number;
+    /** Minimum similarity score threshold (0-1, default 0.3) */
+    minScore?: number;
+    /** Filter results to chunks whose metadata contains all these key-value pairs (exact match) */
+    metadata?: Record<string, string>;
+}
+/** A source entry in the knowledge base */
+interface KbSource {
+    /** Source filename */
+    source: string;
+    /** Number of chunks from this source */
+    chunkCount: number;
+    /** ISO timestamp of when the source was first ingested */
+    createdAt: string;
+}
+/** KB client for server-side knowledge base operations */
+interface KbClient {
+    /**
+     * Ingest files into the knowledge base.
+     *
+     * **Warning**: This is destructive — it deletes ALL existing chunks
+     * for the environment before ingesting the new files.
+     */
+    ingest(files: KbIngestFile[]): Promise<KbIngestResult>;
+    /** Search the knowledge base for relevant chunks */
+    search(query: string, options?: KbSearchOptions): Promise<SearchResult[]>;
+    /** List all sources in the knowledge base */
+    sources(): Promise<KbSource[]>;
+}
+
+type EventType = "session.started" | "tool.called" | "quote.requested" | "quote.succeeded" | "quote.failed" | "link.clicked" | "purchase.completed" | "widget_render" | "widget_click" | "widget_link_click" | "widget_error" | "widget_scroll" | "widget_form_field" | "widget_form_submit" | "user.identified";
+interface ToolCalledProperties {
+    name?: string;
+    type?: "pricing" | "product_info" | "availability" | "support" | "other";
+}
+interface QuoteSucceededProperties {
+    amount?: number;
+    currency?: string;
+}
+interface LinkClickedProperties {
+    url?: string;
+}
+interface PurchaseCompletedProperties {
+    amount?: number;
+    currency?: string;
+}
+interface TrackingContext {
+    /**
+     * MCP request metadata passed through to the API.
+     *
+     * Location varies by MCP library:
+     * - `@vercel/mcp-handler`: `extra._meta`
+     * - `@modelcontextprotocol/sdk`: `request.params._meta`
+     */
+    meta?: Record<string, unknown>;
+    /** Legacy metadata field supported for backward compatibility. */
+    metadata?: Record<string, unknown>;
+    /** Optional explicit correlation fields. */
+    sessionId?: string;
+    traceId?: string;
+    requestId?: string;
+    correlationId?: string;
+    externalUserId?: string;
+    /** Optional explicit envelope fields. */
+    eventId?: string;
+    timestamp?: string | Date;
+    source?: string;
+}
 /**
- * Widget platform types
+ * Modern tracking shape (preferred).
  */
-type WidgetPlatform = "openai" | "mcp-apps";
+interface BaseTrackEvent extends TrackingContext {
+    event: EventType;
+    properties?: Record<string, unknown>;
+}
+type TrackEvent = ({
+    event: "session.started";
+} & BaseTrackEvent) | ({
+    event: "tool.called";
+    properties?: ToolCalledProperties;
+} & BaseTrackEvent) | ({
+    event: "quote.requested";
+} & BaseTrackEvent) | ({
+    event: "quote.succeeded";
+    properties?: QuoteSucceededProperties;
+} & BaseTrackEvent) | ({
+    event: "quote.failed";
+} & BaseTrackEvent) | ({
+    event: "link.clicked";
+    properties?: LinkClickedProperties;
+} & BaseTrackEvent) | ({
+    event: "purchase.completed";
+    properties?: PurchaseCompletedProperties;
+} & BaseTrackEvent) | ({
+    event: "user.identified";
+} & BaseTrackEvent);
 /**
- * Detects which platform the widget is running on.
- *
- * OpenAI injects a global `window.openai` object.
- * MCP Apps runs in a sandboxed iframe and uses postMessage.
+ * Legacy tracking shape supported for existing integrations.
  */
-declare function detectPlatform(): WidgetPlatform;
+interface LegacyTrackEvent extends TrackingContext {
+    eventType: EventType;
+    properties?: Record<string, unknown>;
+    toolName?: string;
+    toolType?: ToolCalledProperties["type"];
+    quoteAmount?: number;
+    quoteCurrency?: string;
+    linkUrl?: string;
+    purchaseAmount?: number;
+    purchaseCurrency?: string;
+}
 /**
- * Check if running on OpenAI platform
+ * Public track input accepted by `client.track()`.
  */
-declare function isOpenAI(): boolean;
+type TrackInput = TrackEvent | LegacyTrackEvent;
+interface TrackingConfig {
+    /** Events API V2 endpoint path. */
+    endpointPath?: string;
+    /** Periodic flush interval for buffered events. */
+    flushIntervalMs?: number;
+    /** Max events per HTTP batch send. */
+    maxBatchSize?: number;
+    /** Max in-memory buffer size before oldest items are dropped. */
+    maxBufferSize?: number;
+    /** Number of retries for retryable failures. */
+    maxRetries?: number;
+    /** Retry backoff base delay. */
+    retryBaseDelayMs?: number;
+    /** Retry backoff max delay. */
+    retryMaxDelayMs?: number;
+    /** Default shutdown timeout when none is provided. */
+    shutdownTimeoutMs?: number;
+}
+interface TrackingShutdownOptions {
+    timeoutMs?: number;
+}
+interface TrackingShutdownResult {
+    timedOut: boolean;
+    pendingEvents: number;
+}
 /**
- * Check if running on MCP Apps platform
+ * Tracking module methods for WaniWaniClient.
  */
-declare function isMCPApps(): boolean;
-
-type ModelContextContentBlock = ContentBlock;
-type ModelContextUpdate = {
-    content?: ModelContextContentBlock[];
-    structuredContent?: Record<string, unknown>;
-};
+interface TrackingClient {
+    /**
+     * Send a one-shot identify event for a user.
+     * userId can be any string: an email, an internal ID, etc.
+     */
+    identify: (userId: string, properties?: Record<string, unknown>, meta?: Record<string, unknown>) => Promise<{
+        eventId: string;
+    }>;
+    /**
+     * Track an event using modern or legacy input shape.
+     * Returns a deterministic event id immediately after enqueue.
+     */
+    track: (event: TrackInput) => Promise<{
+        eventId: string;
+    }>;
+    /**
+     * Flush all currently buffered events.
+     */
+    flush: () => Promise<void>;
+    /**
+     * Flush and stop the transport.
+     */
+    shutdown: (options?: TrackingShutdownOptions) => Promise<TrackingShutdownResult>;
+}
 
 /**
- * Source: https://github.com/openai/openai-apps-sdk-examples/tree/main/src
+ * A request-scoped WaniWani client with meta pre-attached.
+ *
+ * Available as `context.waniwani` inside `createTool` handlers and flow nodes
+ * when the server is wrapped with `withWaniwani()`.
  */
-type OpenAIGlobals<ToolInput = UnknownObject, ToolOutput = UnknownObject, ToolResponseMetadata = UnknownObject, WidgetState = UnknownObject> = {
-    theme: Theme;
-    userAgent: UserAgent;
-    locale: string;
-    maxHeight: number;
-    displayMode: DisplayMode;
-    safeArea: SafeArea;
-    toolInput: ToolInput;
-    toolOutput: ToolOutput | null;
-    toolResponseMetadata: ToolResponseMetadata | null;
-    widgetState: WidgetState | null;
-    setWidgetState: (state: WidgetState) => Promise<void>;
-};
-type API = {
-    callTool: CallTool;
-    sendFollowUpMessage: (args: {
-        prompt: string;
-    }) => Promise<void>;
-    openExternal(payload: {
-        href: string;
-    }): void;
-    requestDisplayMode: RequestDisplayMode;
-};
-type UnknownObject = Record<string, unknown>;
-type Theme = "light" | "dark";
-type SafeAreaInsets = {
-    top: number;
-    bottom: number;
-    left: number;
-    right: number;
-};
-type SafeArea = {
-    insets: SafeAreaInsets;
-};
-type DeviceType = "mobile" | "tablet" | "desktop" | "unknown";
-type UserAgent = {
-    device: {
-        type: DeviceType;
-    };
-    capabilities: {
-        hover: boolean;
-        touch: boolean;
-    };
-};
-/** Display mode */
-type DisplayMode = "pip" | "inline" | "fullscreen";
-type RequestDisplayMode = (args: {
-    mode: DisplayMode;
-}) => Promise<{
-    /**
-     * The granted display mode. The host may reject the request.
-     * For mobile, PiP is always coerced to fullscreen.
-     */
-    mode: DisplayMode;
-}>;
-type CallToolResponse = {
-    result: string;
-};
-/** Calling APIs */
-type CallTool = (name: string, args: Record<string, unknown>) => Promise<CallToolResponse>;
-/** Extra events */
-declare const SET_GLOBALS_EVENT_TYPE = "openai:set_globals";
-declare class SetGlobalsEvent extends CustomEvent<{
-    globals: Partial<OpenAIGlobals>;
-}> {
-    constructor(detail: {
-        globals: Partial<OpenAIGlobals>;
-    });
-}
-/**
- * Global oai object injected by the web sandbox for communicating with chatgpt host page.
- */
-declare global {
-    interface Window {
-        openai: API & OpenAIGlobals;
-        innerBaseUrl: string;
-    }
-    interface WindowEventMap {
-        [SET_GLOBALS_EVENT_TYPE]: SetGlobalsEvent;
-    }
-}
-
-/**
- * Result from calling a tool
- */
-type ToolCallResult = CallToolResult;
-/**
- * Tool result notification (what the host pushes to the widget)
- */
-type ToolResult = CallToolResult;
-/**
- * Host context - all values available from the host.
- */
-type HostContext = {
-    theme: Theme;
-    locale: string;
-    displayMode: DisplayMode;
-    maxHeight: number | null;
-    safeArea: SafeArea | null;
-    toolOutput: UnknownObject | null;
-    toolResponseMetadata: UnknownObject | null;
-    widgetState: UnknownObject | null;
-};
-/**
- * Unified widget client interface that works on both OpenAI and MCP Apps.
- *
- * Platform-specific behavior:
- * - Display mode: OpenAI-only. MCP Apps returns "inline" and requestDisplayMode is a no-op.
- * - Follow-up messages: Unified API, different underlying implementations.
- */
-interface UnifiedWidgetClient {
-    /**
-     * Connect to the host. Must be called before using other methods.
-     * On OpenAI, this is a no-op (already connected via window.openai).
-     * On MCP Apps, this establishes the postMessage connection.
-     */
-    connect(): Promise<void>;
-    /**
-     * Close the connection to the host and clean up resources.
-     * On OpenAI, this is a no-op.
-     * On MCP Apps, this closes the transport and removes event listeners.
-     */
-    close(): Promise<void>;
-    /**
-     * Get the tool output (structured content returned by the tool handler).
-     * This is the main data source for widget rendering.
-     */
-    getToolOutput<T = Record<string, unknown>>(): T | null;
-    /**
-     * Register a callback for when tool results are received.
-     * On OpenAI, this subscribes to toolOutput changes.
-     * On MCP Apps, this sets app.ontoolresult.
-     */
-    onToolResult(callback: (result: ToolResult) => void): () => void;
-    /**
-     * Call another tool on the server.
-     */
-    callTool(name: string, args: Record<string, unknown>): Promise<ToolCallResult>;
-    /**
-     * Open an external URL.
-     * On OpenAI: openai.openExternal({ href })
-     * On MCP Apps: app.sendOpenLink(url)
-     */
-    openExternal(url: string): void;
-    /**
-     * Send a follow-up message to the AI.
-     * On OpenAI: openai.sendFollowUpMessage({ prompt })
-     * On MCP Apps: app.sendMessages([{ role: 'user', content: { type: 'text', text: prompt } }])
-     */
-    sendFollowUp(prompt: string): void | Promise<void>;
-    /**
-     * Update hidden model context for the next assistant turn.
-     * On MCP Apps this uses the standard `ui/update-model-context` request.
-     * On other hosts this may fall back to best-effort behavior.
-     */
-    updateModelContext(context: ModelContextUpdate): Promise<void> | void;
-    /**
-     * Get the current theme.
-     */
-    getTheme(): Theme;
-    /**
-     * Subscribe to theme changes.
-     */
-    onThemeChange(callback: (theme: Theme) => void): () => void;
-    /**
-     * Get the current locale.
-     */
-    getLocale(): string;
-    /**
-     * Get the current display mode.
-     * OpenAI-only: returns "pip" | "inline" | "fullscreen"
-     * MCP Apps: always returns "inline"
-     */
-    getDisplayMode(): DisplayMode;
-    /**
-     * Request a display mode change.
-     * OpenAI-only: requests the mode from the host.
-     * MCP Apps: no-op (returns current mode).
-     */
-    requestDisplayMode(mode: DisplayMode): Promise<DisplayMode>;
-    /**
-     * Subscribe to display mode changes.
-     * OpenAI-only: subscribes to displayMode changes.
-     * MCP Apps: callback is never called.
-     */
-    onDisplayModeChange(callback: (mode: DisplayMode) => void): () => void;
-    /**
-     * Get the safe area insets.
-     * OpenAI-only: returns insets from window.openai.safeArea.
-     * MCP Apps: returns null.
-     */
-    getSafeArea(): SafeArea | null;
-    /**
-     * Subscribe to safe area changes.
-     * OpenAI-only: subscribes to safeArea changes.
-     * MCP Apps: callback is never called.
-     */
-    onSafeAreaChange(callback: (safeArea: SafeArea | null) => void): () => void;
-    /**
-     * Get the max height constraint.
-     * OpenAI-only: returns maxHeight from window.openai.maxHeight.
-     * MCP Apps: returns null.
-     */
-    getMaxHeight(): number | null;
-    /**
-     * Subscribe to max height changes.
-     * OpenAI-only: subscribes to maxHeight changes.
-     * MCP Apps: callback is never called.
-     */
-    onMaxHeightChange(callback: (maxHeight: number | null) => void): () => void;
-    /**
-     * Get the tool response metadata.
-     * OpenAI: returns metadata from window.openai.toolResponseMetadata.
-     * MCP Apps: returns `_meta` from the latest `ui/notifications/tool-result`, if provided by host.
-     */
-    getToolResponseMetadata(): UnknownObject | null;
-    /**
-     * Subscribe to tool response metadata changes.
-     * OpenAI: subscribes to toolResponseMetadata changes.
-     * MCP Apps: fires when tool result `_meta` changes.
-     */
-    onToolResponseMetadataChange(callback: (metadata: UnknownObject | null) => void): () => void;
-    /**
-     * Get the widget state.
-     * OpenAI-only: returns state from window.openai.widgetState.
-     * MCP Apps: returns null.
-     */
-    getWidgetState(): UnknownObject | null;
-    /**
-     * Subscribe to widget state changes.
-     * OpenAI-only: subscribes to widgetState changes.
-     * MCP Apps: callback is never called.
-     */
-    onWidgetStateChange(callback: (state: UnknownObject | null) => void): () => void;
-}
-
-type WidgetCSP = {
-    /** Domains permitted for fetch/XHR network requests */
-    connect_domains?: string[];
-    /** Domains for static assets (images, fonts, scripts, styles) */
-    resource_domains?: string[];
-    /** Origins allowed for iframe embeds (triggers stricter app review) */
-    frame_domains?: string[];
-    /** Origins that can receive openExternal redirects without safe-link modal */
-    redirect_domains?: string[];
+interface ScopedWaniWaniClient {
+    /** Track an event — request meta is automatically merged. */
+    track(event: TrackInput): Promise<{
+        eventId: string;
+    }>;
+    /** Identify a user — request meta is automatically merged. */
+    identify(userId: string, properties?: Record<string, unknown>): Promise<{
+        eventId: string;
+    }>;
+    /** Knowledge base client (no meta needed). */
+    readonly kb: KbClient;
+    /** @internal Resolved API config from withWaniwani(). */
+    readonly _config?: {
+        apiUrl?: string;
+        apiKey?: string;
+    };
+}
+
+type WidgetCSP = {
+    /** Domains permitted for fetch/XHR network requests */
+    connect_domains?: string[];
+    /** Domains for static assets (images, fonts, scripts, styles) */
+    resource_domains?: string[];
+    /** Origins allowed for iframe embeds (triggers stricter app review) */
+    frame_domains?: string[];
+    /** Origins that can receive openExternal redirects without safe-link modal */
+    redirect_domains?: string[];
 };
 type ResourceConfig = {
     /** Unique identifier for the resource */
@@ -314,767 +266,1024 @@ type RegisteredResource = {
     register: (server: McpServer) => Promise<void>;
 };
 
-interface SearchResult {
-    source: string;
-    heading: string;
-    content: string;
-    score: number;
-    metadata?: Record<string, string>;
-}
-/** A file to ingest into the knowledge base */
-interface KbIngestFile {
-    /** Filename (used as chunk source identifier) */
-    filename: string;
-    /** Markdown content of the file */
-    content: string;
-    /** Arbitrary key-value metadata attached to all chunks from this file */
-    metadata?: Record<string, string>;
-}
-/** Response from the ingest endpoint */
-interface KbIngestResult {
-    /** Number of chunks created from the ingested files */
-    chunksIngested: number;
-    /** Number of files successfully processed */
-    filesProcessed: number;
-}
-/** Options for the search method */
-interface KbSearchOptions {
-    /** Number of results to return (1-20, default 5) */
-    topK?: number;
-    /** Minimum similarity score threshold (0-1, default 0.3) */
-    minScore?: number;
-    /** Filter results to chunks whose metadata contains all these key-value pairs (exact match) */
-    metadata?: Record<string, string>;
-}
-/** A source entry in the knowledge base */
-interface KbSource {
-    /** Source filename */
-    source: string;
-    /** Number of chunks from this source */
-    chunkCount: number;
-    /** ISO timestamp of when the source was first ingested */
-    createdAt: string;
+type ToolHandlerContext = {
+    /** Raw MCP request extra data (includes _meta for session extraction) */
+    extra?: {
+        _meta?: Record<string, unknown>;
+    };
+    /** Session-scoped WaniWani client — available when the server is wrapped with withWaniwani() */
+    waniwani?: ScopedWaniWaniClient;
+};
+type ToolConfig<TInput extends ZodRawShapeCompat> = {
+    /** The resource (HTML template) this tool renders. When present, tool returns structuredContent + widget _meta. */
+    resource?: RegisteredResource;
+    /** Tool identifier. Defaults to resource.id when resource is present, required otherwise. */
+    id?: string;
+    /** Display title. Defaults to resource.title when resource is present, required otherwise. */
+    title?: string;
+    /** Action-oriented description for the tool (tells the model WHEN to use it) */
+    description: string;
+    /** UI component description (describes WHAT the widget displays). Falls back to description. Only relevant when resource is present. */
+    widgetDescription?: string;
+    /** Input schema using zod */
+    inputSchema: TInput;
+    /** Optional loading message (defaults to "Loading..."). Only relevant when resource is present. */
+    invoking?: string;
+    /** Optional loaded message (defaults to "Loaded"). Only relevant when resource is present. */
+    invoked?: string;
+    /**
+     * When a widget calls this tool via `tools/call`, should the host auto-inject
+     * the tool's text result into the next follow-up message if the widget does
+     * not send one itself. Defaults to true. Set false for helper tools whose
+     * result is consumed programmatically by the widget.
+     */
+    autoInjectResultText?: boolean;
+    /** Annotations describe the tool's potential impact. */
+    annotations?: {
+        readOnlyHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+        destructiveHint?: boolean;
+    };
+};
+type ToolHandler<TInput extends ZodRawShapeCompat> = (input: ShapeOutput<TInput>, context: ToolHandlerContext) => Promise<{
+    /** Text content to return */
+    text: string;
+    /** Structured data returned as MCP `structuredContent`. */
+    data?: Record<string, unknown>;
+}>;
+type ToolToolCallback<TInput extends ZodRawShapeCompat> = ToolCallback<TInput>;
+type RegisteredTool = {
+    id: string;
+    title: string;
+    description: string;
+    /** Register the tool on the server */
+    register: (server: McpServer) => Promise<void>;
+};
+
+/**
+ * Server-side flow state store.
+ *
+ * Flow state is stored via the WaniWani API, keyed by session ID.
+ * Config comes from env vars (WANIWANI_API_KEY, WANIWANI_API_URL).
+ */
+
+interface FlowStore {
+    get(key: string): Promise<FlowTokenContent | null>;
+    set(key: string, value: FlowTokenContent): Promise<void>;
+    delete(key: string): Promise<void>;
 }
-/** KB client for server-side knowledge base operations */
-interface KbClient {
+
+declare const START: "__start__";
+declare const END: "__end__";
+declare const INTERRUPT: unique symbol;
+declare const WIDGET: unique symbol;
+/** A single question within an interrupt step */
+type InterruptQuestion = {
+    /** Question to ask the user */
+    question: string;
+    /** State key where the answer will be stored */
+    field: string;
+    /** Optional suggestions to present as options */
+    suggestions?: string[];
+    /** Hidden context/instructions for this specific question (not shown to user directly) */
+    context?: string;
+    /** Validation function — runs after the user answers, before advancing to the next node */
+    validate?: (value: unknown) => MaybePromise<Record<string, unknown> | void>;
+};
+/**
+ * Interrupt signal — pauses the flow and asks the user one or more questions.
+ * Single-question and multi-question interrupts use the same type.
+ */
+type InterruptSignal = {
+    readonly __type: typeof INTERRUPT;
+    /** Questions to ask — ask all in one conversational message */
+    questions: InterruptQuestion[];
+    /** Overall hidden context/instructions for the assistant (not shown to user directly) */
+    context?: string;
+};
+type WidgetSignal = {
+    readonly __type: typeof WIDGET;
+    /** The id of the display tool to delegate rendering to */
+    tool: string;
+    /** Data to pass to the display tool */
+    data: Record<string, unknown>;
+    /** Description of what the widget does (for the AI's context) */
+    description?: string;
+    /**
+     * Whether the user is expected to interact with the widget before the flow continues.
+     * Defaults to true. Set to false for informational widgets that should render and then
+     * immediately advance to the next flow step.
+     */
+    interactive?: boolean;
+    /**
+     * State key this widget fills — enables auto-skip when the field is already in state.
+     * Pass this so the engine can skip the widget step when the answer is already known.
+     */
+    field?: string;
+};
+type MaybePromise<T> = T | Promise<T>;
+/** Deep partial — allows partial updates at any nesting level (for z.object state fields). */
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends Record<string, unknown> ? DeepPartial<T[K]> : T[K];
+};
+/**
+ * Extract known (non-index-signature) string keys from a type.
+ * Zod v4's z.object() adds `[key: string]: unknown` to inferred types,
+ * so we filter those out to get only the declared field names.
+ */
+type KnownStringKeys<T> = Extract<keyof {
+    [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
+}, string>;
+/**
+ * Union of all valid field paths for a state type.
+ * - Flat fields produce their key: `"email"`
+ * - `z.object()` fields produce dot-paths to sub-fields: `"driver.name"`, `"driver.license"`
+ * - Arrays and general records (`z.record()`) are treated as flat fields.
+ * - Only 1 level of nesting is supported.
+ */
+type FieldPaths<TState> = {
+    [K in Extract<keyof TState, string>]: NonNullable<TState[K]> extends unknown[] ? K : NonNullable<TState[K]> extends Record<string, unknown> ? KnownStringKeys<NonNullable<TState[K]>> extends never ? K : K | `${K}.${KnownStringKeys<NonNullable<TState[K]>>}` : K;
+}[Extract<keyof TState, string>];
+/** Resolve a dot-path to the value type at that path in TState. */
+type ResolveFieldType<TState, P extends string> = P extends `${infer Parent}.${infer Child}` ? Parent extends keyof TState ? Child extends keyof NonNullable<TState[Parent]> ? NonNullable<TState[Parent]>[Child] : never : never : P extends keyof TState ? TState[P] : never;
+/**
+ * Typed interrupt function — available on the node context.
+ *
+ * First argument: an object where each key is a field path and each value
+ * describes the question for that field. Use dot-paths for nested state fields.
+ * `validate` receives the field's value typed from the Zod schema.
+ *
+ * Second argument (optional): config with overall hidden AI instructions.
+ *
+ * @example
+ * ```ts
+ * // Flat field
+ * interrupt({ breed: { question: "What breed is your pet?" } })
+ *
+ * // Nested field (z.object in state)
+ * interrupt({ "driver.name": { question: "Driver's name?" } })
+ *
+ * // Multiple questions with context
+ * interrupt(
+ *   {
+ *     "driver.name": { question: "Name?" },
+ *     "driver.license": { question: "License?" },
+ *   },
+ *   { context: "Ask both questions naturally." },
+ * )
+ * ```
+ */
+type TypedInterrupt<TState> = (fields: {
+    [P in FieldPaths<TState>]?: {
+        question: string;
+        validate?: (value: ResolveFieldType<TState, P>) => MaybePromise<DeepPartial<TState> | void>;
+        suggestions?: string[];
+        context?: string;
+    };
+}, config?: {
+    /** Overall hidden context/instructions for the assistant (not shown to user directly) */
+    context?: string;
+}) => InterruptSignal;
+/**
+ * Typed showWidget function — available on the node context.
+ * The `field` parameter accepts field paths (flat or dot-path for nested state).
+ */
+type TypedShowWidget<TState> = (tool: RegisteredTool | string, config: {
+    data: Record<string, unknown>;
+    description?: string;
+    interactive?: boolean;
+    field?: FieldPaths<TState>;
+}) => WidgetSignal;
+/**
+ * Context object passed to node handlers.
+ * Provides state, metadata, and typed helper functions for creating signals.
+ */
+type NodeContext<TState> = {
+    /** Current flow state (partial — fields are filled as the flow progresses) */
+    state: Partial<TState>;
+    /** Request metadata from the MCP call */
+    meta?: Record<string, unknown>;
+    /** Create an interrupt signal — pause and ask the user questions */
+    interrupt: TypedInterrupt<TState>;
+    /** Create a widget signal — pause and show a UI widget */
+    showWidget: TypedShowWidget<TState>;
+    /** Session-scoped WaniWani client — available when the server is wrapped with withWaniwani() */
+    waniwani?: ScopedWaniWaniClient;
+};
+/**
+ * Node handler — receives a context object and returns a signal or state updates.
+ * The return value determines behavior:
+ * - `Partial<TState>` → action node (state merged, auto-advance)
+ * - `InterruptSignal` → interrupt (pause, ask user one or more questions)
+ * - `WidgetSignal` → widget step (pause, show widget)
+ */
+type NodeHandler<TState> = (ctx: NodeContext<TState>) => MaybePromise<DeepPartial<TState> | InterruptSignal | WidgetSignal>;
+/**
+ * Condition function for conditional edges.
+ * Receives current state, returns the name of the next node.
+ */
+type ConditionFn<TState> = (state: Partial<TState>) => string | Promise<string>;
+type NodeOptions = {
+    /** Human-readable label for this node (used in funnel visualization and Graphs). */
+    label: string;
+    /** When true, this node is excluded from funnel analytics. */
+    hideFromFunnel?: boolean;
+};
+/**
+ * Config for the object form of `.addNode({ id, run, label?, hideFromFunnel? })`.
+ *
+ * Preferred over the positional form `.addNode(id, run, options?)` — metadata
+ * sits at the top where the eye lands, and the handler is a named field.
+ */
+type AddNodeConfig<TState, TName extends string = string> = {
+    /** Unique node id within the flow. */
+    id: TName;
+    /** Node handler — receives ctx, returns state updates or a signal. */
+    run: NodeHandler<TState>;
+    /** Human-readable label for funnel visualization and graphs. Defaults to `id`. */
+    label?: string;
+    /** When true, this node is excluded from funnel analytics. */
+    hideFromFunnel?: boolean;
+};
+type FlowGraphNode = {
+    id: string;
+    type: "widget" | "interrupt" | "action";
+    label: string;
+    hideFromFunnel?: boolean;
+};
+type FlowGraphEdge = {
+    from: string;
+    to: string;
+    type: "direct";
+} | {
+    from: string;
+    to: string[];
+    type: "conditional";
+};
+type FlowGraph = {
+    flowId: string;
+    title: string;
+    nodes: FlowGraphNode[];
+    edges: FlowGraphEdge[];
+};
+type FlowConfig = {
+    /** Unique identifier for the flow (becomes the MCP tool name) */
+    id: string;
+    /** Display title */
+    title: string;
+    /** Description for the AI (explains when to use this flow) */
+    description: string;
+    /**
+     * Define the flow's state — each field the flow collects.
+     * Keys are the field names used in `interrupt({ field })`,
+     * values are Zod schemas with `.describe()`.
+     *
+     * The state definition serves two purposes:
+     * 1. Type inference — `TState` is automatically derived, no explicit generic needed
+     * 2. AI protocol — field names, types, and descriptions are included in the tool
+     *    description so the AI can pre-fill answers via `_meta.flow.state`
+     *
+     * @example
+     * ```ts
+     * state: {
+     *   country: z.string().describe("Country the business is based in"),
+     *   status: z.enum(["registered", "unregistered"]).describe("Business registration status"),
+     * }
+     * ```
+     */
+    state: Record<string, z.ZodType>;
+    /**
+     * If true, instruct the agent to omit PII (names, emails, phones, addresses,
+     * IDs, ages, birthdates) from the `intent` and `context` fields. Only adds a
+     * guidance line to the tool description — does not redact server-side.
+     */
+    omitIntentPII?: boolean;
+    /** Optional tool annotations */
+    annotations?: {
+        readOnlyHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+        destructiveHint?: boolean;
+    };
+};
+/**
+ * Infer the runtime state type from a flow's state schema definition.
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   state: {
+ *     country: z.enum(["FR", "DE"]),
+ *     status: z.enum(["registered", "unregistered"]),
+ *   }
+ * };
+ * type MyState = InferFlowState<typeof config.state>;
+ * // { country: "FR" | "DE"; status: "registered" | "unregistered" }
+ * ```
+ */
+type InferFlowState<T extends Record<string, z.ZodType>> = {
+    [K in keyof T]: z.infer<T[K]>;
+};
+/**
+ * Flow tool handler — uses shared MCP types (`RequestHandlerExtra`, `CallToolResult`)
+ * so it's assignable to both MCP SDK's `ToolCallback` and Skybridge's `ToolHandler`.
+ */
+type FlowToolHandler = (args: Record<string, unknown>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => CallToolResult | Promise<CallToolResult>;
+/**
+ * A compiled flow — can be registered on an McpServer.
+ *
+ * Exposes MCP-compatible `name`, `config`, and `handler` so it can be
+ * registered directly: `server.registerTool(flow.name, flow.config, flow.handler)`
+ */
+type RegisteredFlow = {
+    /** Tool name — pass to `server.registerTool(flow.name, flow.config, flow.handler)`. */
+    name: string;
+    /** Tool config object — pass to `server.registerTool(flow.name, flow.config, flow.handler)`. */
+    config: {
+        title: string;
+        description: string;
+        inputSchema: ZodRawShapeCompat;
+        annotations?: {
+            readOnlyHint?: boolean;
+            idempotentHint?: boolean;
+            openWorldHint?: boolean;
+            destructiveHint?: boolean;
+        };
+    };
+    /** Tool callback — pass to `server.registerTool(flow.name, flow.config, flow.handler)`. */
+    handler: FlowToolHandler;
+    /** Register this flow on an MCP server. Shorthand for `server.registerTool(flow.name, flow.config, flow.handler)`. */
+    register: (server: McpServer) => Promise<void>;
+    /** Returns a Mermaid `flowchart TD` diagram of the flow graph. */
+    graph: () => string;
+    flowGraph: FlowGraph;
+};
+type FlowTokenContent = {
+    step?: string;
+    state: Record<string, unknown>;
+    field?: string;
+    widgetId?: string;
+};
+type InterruptQuestionData = {
+    question: string;
+    field: string;
+    suggestions?: string[];
+    context?: string;
+};
+type FlowInterruptContent = {
+    status: "interrupt";
+    /** Single-question shorthand */
+    question?: string;
+    field?: string;
+    suggestions?: string[];
+    /** Multi-question */
+    questions?: InterruptQuestionData[];
+    context?: string;
+};
+type FlowWidgetContent = {
+    status: "widget";
+    /** Display tool to call */
+    tool: string;
+    /** Data to pass to the display tool */
+    data: Record<string, unknown>;
+    description?: string;
+    /** Whether the widget expects user interaction before continuing */
+    interactive?: boolean;
+};
+type FlowCompleteContent = {
+    status: "complete";
+};
+type FlowErrorContent = {
+    status: "error";
+    error: string;
+};
+
+/**
+ * A LangGraph-inspired state graph builder for MCP tools.
+ *
+ * @example
+ * ```ts
+ * const flow = new StateGraph<MyState>({
+ *   id: "onboarding",
+ *   title: "User Onboarding",
+ *   description: "Guides users through onboarding",
+ * })
+ *   .addNode({
+ *     id: "ask_name",
+ *     run: ({ interrupt }) => interrupt({ question: "What's your name?", field: "name" }),
+ *   })
+ *   .addNode({
+ *     id: "greet",
+ *     run: ({ state }) => ({ greeting: `Hello ${state.name}!` }),
+ *   })
+ *   .addEdge(START, "ask_name")
+ *   .addEdge("ask_name", "greet")
+ *   .addEdge("greet", END)
+ *   .compile();
+ * ```
+ */
+declare class StateGraph<TState extends Record<string, unknown>, TNodes extends string = never> {
+    private nodes;
+    private edges;
+    private nodeOptions;
+    private config;
+    constructor(config: FlowConfig);
     /**
-     * Ingest files into the knowledge base.
+     * Add a node with a handler.
      *
-     * **Warning**: This is destructive — it deletes ALL existing chunks
-     * for the environment before ingesting the new files.
+     * The handler receives a context object with `state`, `meta`, `interrupt`, and `showWidget`.
+     *
+     * @example
+     * ```ts
+     * .addNode({
+     *   id: "ask_name",
+     *   label: "Ask for name",
+     *   run: ({ interrupt }) => interrupt({ question: "What's your name?", field: "name" }),
+     * })
+     * ```
      */
-    ingest(files: KbIngestFile[]): Promise<KbIngestResult>;
-    /** Search the knowledge base for relevant chunks */
-    search(query: string, options?: KbSearchOptions): Promise<SearchResult[]>;
-    /** List all sources in the knowledge base */
-    sources(): Promise<KbSource[]>;
-}
-
-type EventType = "session.started" | "tool.called" | "quote.requested" | "quote.succeeded" | "quote.failed" | "link.clicked" | "purchase.completed" | "widget_render" | "widget_click" | "widget_link_click" | "widget_error" | "widget_scroll" | "widget_form_field" | "widget_form_submit" | "user.identified";
-interface ToolCalledProperties {
-    name?: string;
-    type?: "pricing" | "product_info" | "availability" | "support" | "other";
-}
-interface QuoteSucceededProperties {
-    amount?: number;
-    currency?: string;
-}
-interface LinkClickedProperties {
-    url?: string;
-}
-interface PurchaseCompletedProperties {
-    amount?: number;
-    currency?: string;
-}
-interface TrackingContext {
+    addNode<TName extends string>(config: AddNodeConfig<TState, TName>): StateGraph<TState, TNodes | TName>;
     /**
-     * MCP request metadata passed through to the API.
+     * @deprecated Use the object form: `.addNode({ id, run, label? })`.
+     * The positional form will be removed in v0.13.0
+     */
+    addNode<TName extends string>(name: TName, handler: NodeHandler<TState>, options?: NodeOptions): StateGraph<TState, TNodes | TName>;
+    /**
+     * Add a direct edge between two nodes.
      *
-     * Location varies by MCP library:
-     * - `@vercel/mcp-handler`: `extra._meta`
-     * - `@modelcontextprotocol/sdk`: `request.params._meta`
+     * Use `START` as `from` to set the entry point.
+     * Use `END` as `to` to mark a terminal node.
      */
-    meta?: Record<string, unknown>;
-    /** Legacy metadata field supported for backward compatibility. */
-    metadata?: Record<string, unknown>;
-    /** Optional explicit correlation fields. */
-    sessionId?: string;
-    traceId?: string;
-    requestId?: string;
-    correlationId?: string;
-    externalUserId?: string;
-    /** Optional explicit envelope fields. */
-    eventId?: string;
-    timestamp?: string | Date;
-    source?: string;
+    addEdge(from: typeof START | TNodes, to: TNodes | typeof END): this;
+    /**
+     * Add a conditional edge from a node.
+     *
+     * The condition function receives current state and returns the name of the next node.
+     */
+    addConditionalEdge(from: TNodes, condition: (state: Partial<TState>) => TNodes | typeof END | Promise<TNodes | typeof END>): this;
+    /**
+     * Generate a Mermaid `flowchart TD` diagram of the graph.
+     *
+     * Direct edges use solid arrows. Conditional edges use a dashed arrow
+     * to a placeholder since branch targets are determined at runtime.
+     *
+     * @example
+     * ```ts
+     * console.log(graph.graph());
+     * // flowchart TD
+     * //   __start__((Start))
+     * //   ask_name[ask_name]
+     * //   greet[greet]
+     * //   __end__((End))
+     * //   __start__ --> ask_name
+     * //   ask_name --> greet
+     * //   greet --> __end__
+     * ```
+     */
+    graph(): string;
+    /**
+     * Compile the graph into a RegisteredFlow that can be registered on an McpServer.
+     *
+     * Validates the graph structure and returns a registration-compatible object.
+     */
+    compile(options?: {
+        store?: FlowStore;
+    }): RegisteredFlow;
+    private validate;
 }
+
 /**
- * Modern tracking shape (preferred).
+ * Create a new flow graph — convenience factory for `new StateGraph()`.
+ *
+ * The state type is automatically inferred from the `state` definition —
+ * no explicit generic parameter needed.
+ *
+ * @example
+ * ```ts
+ * import { createFlow, interrupt, START, END } from "@waniwani/sdk/mcp";
+ * import { z } from "zod";
+ *
+ * const flow = createFlow({
+ *   id: "onboarding",
+ *   title: "User Onboarding",
+ *   description: "Guides users through onboarding. Use when a user wants to get started.",
+ *   state: {
+ *     name: z.string().describe("The user's name"),
+ *     email: z.string().describe("The user's email address"),
+ *   },
+ * })
+ *   .addNode({
+ *     id: "ask_name",
+ *     run: () => interrupt({ question: "What's your name?", field: "name" }),
+ *   })
+ *   .addNode({
+ *     id: "ask_email",
+ *     run: () => interrupt({ question: "What's your email?", field: "email" }),
+ *   })
+ *   .addEdge(START, "ask_name")
+ *   .addEdge("ask_name", "ask_email")
+ *   .addEdge("ask_email", END)
+ *   .compile();
+ * ```
  */
-interface BaseTrackEvent extends TrackingContext {
-    event: EventType;
-    properties?: Record<string, unknown>;
-}
-type TrackEvent = ({
-    event: "session.started";
-} & BaseTrackEvent) | ({
-    event: "tool.called";
-    properties?: ToolCalledProperties;
-} & BaseTrackEvent) | ({
-    event: "quote.requested";
-} & BaseTrackEvent) | ({
-    event: "quote.succeeded";
-    properties?: QuoteSucceededProperties;
-} & BaseTrackEvent) | ({
-    event: "quote.failed";
-} & BaseTrackEvent) | ({
-    event: "link.clicked";
-    properties?: LinkClickedProperties;
-} & BaseTrackEvent) | ({
-    event: "purchase.completed";
-    properties?: PurchaseCompletedProperties;
-} & BaseTrackEvent) | ({
-    event: "user.identified";
-} & BaseTrackEvent);
+declare function createFlow<const TSchema extends Record<string, z.ZodType>>(config: Omit<FlowConfig, "state"> & {
+    state: TSchema;
+}): StateGraph<InferFlowState<TSchema>>;
+
 /**
- * Legacy tracking shape supported for existing integrations.
+ * Mark a Zod schema as PII — its value will be replaced with `"REDACTED"` in
+ * any `tool.called` event payload sent to the WaniWani API. The handler still
+ * receives the original value; only the tracked copy is scrubbed.
+ *
+ * Apply at the end of the schema chain so the marker is attached to the final
+ * schema:
+ *
+ * ```ts
+ * ages: redacted(z.string().describe("Comma-separated ages")),
+ * zipcode: redacted(z.string().describe("Spanish postal code")),
+ * ```
+ *
+ * Uses Zod v4's `.meta()` registry, so the marker is preserved across schema
+ * clones (`.optional()`, `.default()`, etc.).
  */
-interface LegacyTrackEvent extends TrackingContext {
-    eventType: EventType;
-    properties?: Record<string, unknown>;
-    toolName?: string;
-    toolType?: ToolCalledProperties["type"];
-    quoteAmount?: number;
-    quoteCurrency?: string;
-    linkUrl?: string;
-    purchaseAmount?: number;
-    purchaseCurrency?: string;
-}
+declare function redacted<T extends z.ZodType>(schema: T): T;
+
+type WithDecodedState = {
+    decodedState: FlowTokenContent | null;
+};
+type FlowTestResult = (FlowInterruptContent & WithDecodedState) | (FlowWidgetContent & WithDecodedState) | (FlowCompleteContent & WithDecodedState) | (FlowErrorContent & WithDecodedState);
+declare function createFlowTestHarness(flow: RegisteredFlow, options?: {
+    stateStore?: FlowStore;
+}): Promise<{
+    start(intent: string, stateUpdates?: Record<string, unknown>, context?: string): Promise<FlowTestResult>;
+    continueWith(stateUpdates?: Record<string, unknown>): Promise<FlowTestResult>;
+    resetWith(stateUpdates: Record<string, unknown>): Promise<FlowTestResult>;
+    lastState(): Promise<FlowTokenContent | null>;
+}>;
+
 /**
- * Public track input accepted by `client.track()`.
+ * Generic key-value store backed by the WaniWani API.
+ *
+ * Values are stored as JSON objects (`Record<string, unknown>`) in the
+ * `/api/mcp/redis/*` endpoints. Tenant isolation is handled by the API key.
+ *
+ * Config is read from env vars:
+ * - `WANIWANI_API_KEY` (required)
+ * - `WANIWANI_API_URL` (optional, defaults to https://app.waniwani.ai)
+ * - `WANIWANI_ENCRYPTION_KEY` (optional, base64-encoded 32-byte key for AES-256-GCM encryption)
  */
-type TrackInput = TrackEvent | LegacyTrackEvent;
-interface TrackingConfig {
-    /** Events API V2 endpoint path. */
-    endpointPath?: string;
-    /** Periodic flush interval for buffered events. */
-    flushIntervalMs?: number;
-    /** Max events per HTTP batch send. */
-    maxBatchSize?: number;
-    /** Max in-memory buffer size before oldest items are dropped. */
-    maxBufferSize?: number;
-    /** Number of retries for retryable failures. */
-    maxRetries?: number;
-    /** Retry backoff base delay. */
-    retryBaseDelayMs?: number;
-    /** Retry backoff max delay. */
-    retryMaxDelayMs?: number;
-    /** Default shutdown timeout when none is provided. */
-    shutdownTimeoutMs?: number;
-}
-interface TrackingShutdownOptions {
-    timeoutMs?: number;
+interface KvStore<T = Record<string, unknown>> {
+    get(key: string): Promise<T | null>;
+    set(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
 }
-interface TrackingShutdownResult {
-    timedOut: boolean;
-    pendingEvents: number;
+declare class WaniwaniKvStore<T = Record<string, unknown>> implements KvStore<T> {
+    private get baseUrl();
+    private get apiKey();
+    private get encryptionKey();
+    get(key: string): Promise<T | null>;
+    set(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    private request;
 }
+
 /**
- * Tracking module methods for WaniWaniClient.
+ * In-memory KvStore implementation.
+ *
+ * State lives in a `Map` for the lifetime of the process — nothing is
+ * persisted, nothing is shared across instances. Use for local development
+ * and tests. For production, plug in a Redis/Upstash/CF-KV adapter or set
+ * `WANIWANI_API_KEY` to use the hosted store.
  */
-interface TrackingClient {
-    /**
-     * Send a one-shot identify event for a user.
-     * userId can be any string: an email, an internal ID, etc.
-     */
-    identify: (userId: string, properties?: Record<string, unknown>, meta?: Record<string, unknown>) => Promise<{
-        eventId: string;
-    }>;
-    /**
-     * Track an event using modern or legacy input shape.
-     * Returns a deterministic event id immediately after enqueue.
-     */
-    track: (event: TrackInput) => Promise<{
-        eventId: string;
-    }>;
-    /**
-     * Flush all currently buffered events.
-     */
-    flush: () => Promise<void>;
-    /**
-     * Flush and stop the transport.
-     */
-    shutdown: (options?: TrackingShutdownOptions) => Promise<TrackingShutdownResult>;
+
+declare class MemoryKvStore<T = Record<string, unknown>> implements KvStore<T> {
+    private readonly map;
+    get(key: string): Promise<T | null>;
+    set(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
 }
 
 /**
- * A request-scoped WaniWani client with meta pre-attached.
+ * Server-side API route handler for widget tracking events.
  *
- * Available as `context.waniwani` inside `createTool` handlers and flow nodes
- * when the server is wrapped with `withWaniwani()`.
+ * Receives batched events from the `useWaniwani` React hook and forwards them
+ * to the WaniWani backend using the server-side SDK.
+ *
+ * @example Next.js App Router
+ * ```typescript
+ * // app/api/waniwani/track/route.ts
+ * import { createTrackingRoute } from "@waniwani/sdk/mcp";
+ *
+ * const handler = createTrackingRoute({
+ *   apiKey: process.env.WANIWANI_API_KEY,
+ *   apiUrl: process.env.WANIWANI_API_URL,
+ * });
+ *
+ * export { handler as POST };
+ * ```
  */
-interface ScopedWaniWaniClient {
-    /** Track an event — request meta is automatically merged. */
-    track(event: TrackInput): Promise<{
-        eventId: string;
-    }>;
-    /** Identify a user — request meta is automatically merged. */
-    identify(userId: string, properties?: Record<string, unknown>): Promise<{
-        eventId: string;
-    }>;
-    /** Knowledge base client (no meta needed). */
-    readonly kb: KbClient;
-    /** @internal Resolved API config from withWaniwani(). */
-    readonly _config?: {
-        apiUrl?: string;
-        apiKey?: string;
-    };
+interface TrackingRouteOptions {
+    /** API key for the WaniWani backend. Defaults to WANIWANI_API_KEY env var. */
+    apiKey?: string;
+    /** Base URL for the WaniWani backend. Defaults to https://app.waniwani.ai. */
+    apiUrl?: string;
 }
-
-type ToolHandlerContext = {
-    /** Raw MCP request extra data (includes _meta for session extraction) */
-    extra?: {
-        _meta?: Record<string, unknown>;
-    };
-    /** Session-scoped WaniWani client — available when the server is wrapped with withWaniwani() */
-    waniwani?: ScopedWaniWaniClient;
-};
-type ToolConfig<TInput extends ZodRawShapeCompat> = {
-    /** The resource (HTML template) this tool renders. When present, tool returns structuredContent + widget _meta. */
-    resource?: RegisteredResource;
-    /** Tool identifier. Defaults to resource.id when resource is present, required otherwise. */
-    id?: string;
-    /** Display title. Defaults to resource.title when resource is present, required otherwise. */
-    title?: string;
-    /** Action-oriented description for the tool (tells the model WHEN to use it) */
-    description: string;
-    /** UI component description (describes WHAT the widget displays). Falls back to description. Only relevant when resource is present. */
-    widgetDescription?: string;
-    /** Input schema using zod */
-    inputSchema: TInput;
-    /** Optional loading message (defaults to "Loading..."). Only relevant when resource is present. */
-    invoking?: string;
-    /** Optional loaded message (defaults to "Loaded"). Only relevant when resource is present. */
-    invoked?: string;
-    /**
-     * When a widget calls this tool via `tools/call`, should the host auto-inject
-     * the tool's text result into the next follow-up message if the widget does
-     * not send one itself. Defaults to true. Set false for helper tools whose
-     * result is consumed programmatically by the widget.
-     */
-    autoInjectResultText?: boolean;
-    /** Annotations describe the tool's potential impact. */
-    annotations?: {
-        readOnlyHint?: boolean;
-        idempotentHint?: boolean;
-        openWorldHint?: boolean;
-        destructiveHint?: boolean;
-    };
-};
-type ToolHandler<TInput extends ZodRawShapeCompat> = (input: ShapeOutput<TInput>, context: ToolHandlerContext) => Promise<{
-    /** Text content to return */
-    text: string;
-    /** Structured data returned as MCP `structuredContent`. */
-    data?: Record<string, unknown>;
-}>;
-type ToolToolCallback<TInput extends ZodRawShapeCompat> = ToolCallback<TInput>;
-type RegisteredTool = {
-    id: string;
-    title: string;
-    description: string;
-    /** Register the tool on the server */
-    register: (server: McpServer) => Promise<void>;
-};
+/**
+ * Creates a POST handler that receives tracking events from `useWaniwani`
+ * and forwards them to the WaniWani backend.
+ */
+declare function createTrackingRoute(options?: TrackingRouteOptions): (request: Request) => Promise<Response>;
 
 /**
- * Server-side flow state store.
+ * WaniWani SDK Client
  *
- * Flow state is stored via the WaniWani API, keyed by session ID.
- * Config comes from env vars (WANIWANI_API_KEY, WANIWANI_API_URL).
+ * Extends with each module:
+ * - TrackingClient: track(), flush(), shutdown()
+ *
+ * Pass this client to framework adapters:
+ * - `toNextJsHandler(wani, { ... })` for Next.js route handlers
  */
-
-interface FlowStore {
-    get(key: string): Promise<FlowTokenContent | null>;
-    set(key: string, value: FlowTokenContent): Promise<void>;
-    delete(key: string): Promise<void>;
+interface WaniWaniClient extends TrackingClient {
+    /** @internal Resolved config — used by framework adapters */
+    readonly _config: InternalConfig;
+    /** Knowledge base client for ingestion, search, and source listing */
+    readonly kb: KbClient;
+}
+interface InternalConfig {
+    apiUrl: string;
+    apiKey: string | undefined;
+    tracking: Required<TrackingConfig>;
 }
 
-declare const START: "__start__";
-declare const END: "__end__";
-declare const INTERRUPT: unique symbol;
-declare const WIDGET: unique symbol;
-/** A single question within an interrupt step */
-type InterruptQuestion = {
-    /** Question to ask the user */
-    question: string;
-    /** State key where the answer will be stored */
-    field: string;
-    /** Optional suggestions to present as options */
-    suggestions?: string[];
-    /** Hidden context/instructions for this specific question (not shown to user directly) */
-    context?: string;
-    /** Validation function — runs after the user answers, before advancing to the next node */
-    validate?: (value: unknown) => MaybePromise<Record<string, unknown> | void>;
-};
+type WaniwaniTracker = Pick<WaniWaniClient, "flush" | "track" | "identify" | "kb" | "_config">;
+
+type UnknownRecord = Record<string, unknown>;
 /**
- * Interrupt signal — pauses the flow and asks the user one or more questions.
- * Single-question and multi-question interrupts use the same type.
+ * Options for withWaniwani().
  */
-type InterruptSignal = {
-    readonly __type: typeof INTERRUPT;
-    /** Questions to ask — ask all in one conversational message */
-    questions: InterruptQuestion[];
-    /** Overall hidden context/instructions for the assistant (not shown to user directly) */
-    context?: string;
-};
-type WidgetSignal = {
-    readonly __type: typeof WIDGET;
-    /** The id of the display tool to delegate rendering to */
-    tool: string;
-    /** Data to pass to the display tool */
-    data: Record<string, unknown>;
-    /** Description of what the widget does (for the AI's context) */
-    description?: string;
+type WithWaniwaniOptions = {
     /**
-     * Whether the user is expected to interact with the widget before the flow continues.
-     * Defaults to true. Set to false for informational widgets that should render and then
-     * immediately advance to the next flow step.
+     * The WaniWani client instance. When omitted, a client is created
+     * automatically using the global config registered by `defineConfig()`,
+     * falling back to env vars.
      */
-    interactive?: boolean;
+    client?: WaniwaniTracker;
     /**
-     * State key this widget fills — enables auto-skip when the field is already in state.
-     * Pass this so the engine can skip the widget step when the answer is already known.
+     * Optional explicit tool type. Defaults to `"other"`.
+     */
+    toolType?: ToolCalledProperties["type"] | ((toolName: string) => ToolCalledProperties["type"] | undefined);
+    /**
+     * Optional metadata merged into every tracked event.
+     */
+    metadata?: UnknownRecord;
+    /**
+     * Flush tracking transport after each tool call.
+     */
+    flushAfterToolCall?: boolean;
+    /**
+     * Optional error callback for non-fatal tracking errors.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Inject widget tracking config into tool response `_meta.waniwani` so browser
+     * widgets can send events directly to the WaniWani backend.
+     *
+     * Always injects `endpoint`. Injects `token` when an API key is configured
+     * and token minting succeeds.
+     *
+     * @default true
+     */
+    injectWidgetToken?: boolean;
+    /**
+     * List of field names to strip from known location `_meta` entries
+     * (`openai/userLocation`, `waniwani/geoLocation`, `waniwani/userLocation`)
+     * before events are sent to the WaniWani API. Applied to both the
+     * request-level `_meta` and any `_meta` on the tool response.
+     *
+     * Pass e.g. `["latitude", "longitude"]` to drop coordinates only, or
+     * `["latitude", "longitude", "city", "region"]` to keep just `country`.
+     * Empty/omitted = no redaction.
+     *
+     * @default []
+     */
+    stripLocationFields?: readonly string[];
+    /**
+     * Replace `input.stateUpdates[field]` with `"REDACTED"` for any field
+     * marked via `redacted()` on a flow state schema. When `false` (default),
+     * the declarative markers are ignored and raw values are tracked.
+     *
+     * Wire this to an env var when you want real values in development logs
+     * but redacted values in production.
+     *
+     * @default false
      */
-    field?: string;
-};
-type MaybePromise<T> = T | Promise<T>;
-/** Deep partial — allows partial updates at any nesting level (for z.object state fields). */
-type DeepPartial<T> = {
-    [K in keyof T]?: T[K] extends Record<string, unknown> ? DeepPartial<T[K]> : T[K];
+    applyFieldRedactions?: boolean;
 };
 /**
- * Extract known (non-index-signature) string keys from a type.
- * Zod v4's z.object() adds `[key: string]: unknown` to inferred types,
- * so we filter those out to get only the declared field names.
+ * Wrap an MCP server so tool handlers automatically emit `tool.called` events.
+ *
+ * The wrapper intercepts `server.registerTool(...)` for future registrations
+ * and also walks `server._registeredTools` to wrap any tools already registered
+ * at the time of the call. This means either call order works:
+ *
+ *   withWaniwani(server); server.registerTool(...);   // wrap then register
+ *   server.registerTool(...); withWaniwani(server);   // register then wrap
+ *
+ * When `injectWidgetToken` is enabled (default), tracking config is injected
+ * into tool response `_meta.waniwani` so browser widgets can post events
+ * directly to the WaniWani backend without a server-side proxy.
+ *
+ * Widget metadata declared on the tool **definition** (e.g. skybridge's
+ * `registerWidget`, raw MCP `_meta["ui/resourceUri"]` / `_meta.ui.resourceUri`,
+ * OpenAI's `_meta["openai/outputTemplate"]`) is also forwarded into each tool
+ * result's `_meta`, so chat UIs that only see tool results (and not
+ * `tools/list`) can still render widgets. Handler-set keys take precedence.
  */
-type KnownStringKeys<T> = Extract<keyof {
-    [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
-}, string>;
+declare function withWaniwani(server: McpServer, options?: WithWaniwaniOptions): Promise<McpServer>;
+
 /**
- * Union of all valid field paths for a state type.
- * - Flat fields produce their key: `"email"`
- * - `z.object()` fields produce dot-paths to sub-fields: `"driver.name"`, `"driver.license"`
- * - Arrays and general records (`z.record()`) are treated as flat fields.
- * - Only 1 level of nesting is supported.
+ * Widget platform types
  */
-type FieldPaths<TState> = {
-    [K in Extract<keyof TState, string>]: NonNullable<TState[K]> extends unknown[] ? K : NonNullable<TState[K]> extends Record<string, unknown> ? KnownStringKeys<NonNullable<TState[K]>> extends never ? K : K | `${K}.${KnownStringKeys<NonNullable<TState[K]>>}` : K;
-}[Extract<keyof TState, string>];
-/** Resolve a dot-path to the value type at that path in TState. */
-type ResolveFieldType<TState, P extends string> = P extends `${infer Parent}.${infer Child}` ? Parent extends keyof TState ? Child extends keyof NonNullable<TState[Parent]> ? NonNullable<TState[Parent]>[Child] : never : never : P extends keyof TState ? TState[P] : never;
+type WidgetPlatform = "openai" | "mcp-apps";
 /**
- * Typed interrupt function — available on the node context.
- *
- * First argument: an object where each key is a field path and each value
- * describes the question for that field. Use dot-paths for nested state fields.
- * `validate` receives the field's value typed from the Zod schema.
- *
- * Second argument (optional): config with overall hidden AI instructions.
- *
- * @example
- * ```ts
- * // Flat field
- * interrupt({ breed: { question: "What breed is your pet?" } })
+ * Detects which platform the widget is running on.
  *
- * // Nested field (z.object in state)
- * interrupt({ "driver.name": { question: "Driver's name?" } })
+ * OpenAI injects a global `window.openai` object.
+ * MCP Apps runs in a sandboxed iframe and uses postMessage.
  *
- * // Multiple questions with context
- * interrupt(
- *   {
- *     "driver.name": { question: "Name?" },
- *     "driver.license": { question: "License?" },
- *   },
- *   { context: "Ask both questions naturally." },
- * )
- * ```
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
  */
-type TypedInterrupt<TState> = (fields: {
-    [P in FieldPaths<TState>]?: {
-        question: string;
-        validate?: (value: ResolveFieldType<TState, P>) => MaybePromise<DeepPartial<TState> | void>;
-        suggestions?: string[];
-        context?: string;
-    };
-}, config?: {
-    /** Overall hidden context/instructions for the assistant (not shown to user directly) */
-    context?: string;
-}) => InterruptSignal;
+declare function detectPlatform(): WidgetPlatform;
 /**
- * Typed showWidget function — available on the node context.
- * The `field` parameter accepts field paths (flat or dot-path for nested state).
+ * Check if running on OpenAI platform.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
  */
-type TypedShowWidget<TState> = (tool: RegisteredTool | string, config: {
-    data: Record<string, unknown>;
-    description?: string;
-    interactive?: boolean;
-    field?: FieldPaths<TState>;
-}) => WidgetSignal;
+declare function isOpenAI(): boolean;
 /**
- * Context object passed to node handlers.
- * Provides state, metadata, and typed helper functions for creating signals.
+ * Check if running on MCP Apps platform.
+ *
+ * @deprecated Legacy MCP-widget-in-host stack. Preserved for back-compat; will move to
+ *   `@waniwani/sdk/legacy/react` in a future minor release.
  */
-type NodeContext<TState> = {
-    /** Current flow state (partial — fields are filled as the flow progresses) */
-    state: Partial<TState>;
-    /** Request metadata from the MCP call */
-    meta?: Record<string, unknown>;
-    /** Create an interrupt signal — pause and ask the user questions */
-    interrupt: TypedInterrupt<TState>;
-    /** Create a widget signal — pause and show a UI widget */
-    showWidget: TypedShowWidget<TState>;
-    /** Session-scoped WaniWani client — available when the server is wrapped with withWaniwani() */
-    waniwani?: ScopedWaniWaniClient;
+declare function isMCPApps(): boolean;
+
+type ModelContextContentBlock = ContentBlock;
+type ModelContextUpdate = {
+    content?: ModelContextContentBlock[];
+    structuredContent?: Record<string, unknown>;
 };
+
 /**
- * Node handler — receives a context object and returns a signal or state updates.
- * The return value determines behavior:
- * - `Partial<TState>` → action node (state merged, auto-advance)
- * - `InterruptSignal` → interrupt (pause, ask user one or more questions)
- * - `WidgetSignal` → widget step (pause, show widget)
- */
-type NodeHandler<TState> = (ctx: NodeContext<TState>) => MaybePromise<DeepPartial<TState> | InterruptSignal | WidgetSignal>;
-/**
- * Condition function for conditional edges.
- * Receives current state, returns the name of the next node.
+ * Source: https://github.com/openai/openai-apps-sdk-examples/tree/main/src
  */
-type ConditionFn<TState> = (state: Partial<TState>) => string | Promise<string>;
-type NodeOptions = {
-    /** Human-readable label for this node (used in funnel visualization and Graphs). */
-    label: string;
-    /** When true, this node is excluded from funnel analytics. */
-    hideFromFunnel?: boolean;
+type OpenAIGlobals<ToolInput = UnknownObject, ToolOutput = UnknownObject, ToolResponseMetadata = UnknownObject, WidgetState = UnknownObject> = {
+    theme: Theme;
+    userAgent: UserAgent;
+    locale: string;
+    maxHeight: number;
+    displayMode: DisplayMode;
+    safeArea: SafeArea;
+    toolInput: ToolInput;
+    toolOutput: ToolOutput | null;
+    toolResponseMetadata: ToolResponseMetadata | null;
+    widgetState: WidgetState | null;
+    setWidgetState: (state: WidgetState) => Promise<void>;
 };
-type FlowGraphNode = {
-    id: string;
-    type: "widget" | "interrupt" | "action";
-    label: string;
-    hideFromFunnel?: boolean;
+type API = {
+    callTool: CallTool;
+    sendFollowUpMessage: (args: {
+        prompt: string;
+    }) => Promise<void>;
+    openExternal(payload: {
+        href: string;
+    }): void;
+    requestDisplayMode: RequestDisplayMode;
 };
-type FlowGraphEdge = {
-    from: string;
-    to: string;
-    type: "direct";
-} | {
-    from: string;
-    to: string[];
-    type: "conditional";
+type UnknownObject = Record<string, unknown>;
+type Theme = "light" | "dark";
+type SafeAreaInsets = {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
 };
-type FlowGraph = {
-    flowId: string;
-    title: string;
-    nodes: FlowGraphNode[];
-    edges: FlowGraphEdge[];
+type SafeArea = {
+    insets: SafeAreaInsets;
 };
-type FlowConfig = {
-    /** Unique identifier for the flow (becomes the MCP tool name) */
-    id: string;
-    /** Display title */
-    title: string;
-    /** Description for the AI (explains when to use this flow) */
-    description: string;
-    /**
-     * Define the flow's state — each field the flow collects.
-     * Keys are the field names used in `interrupt({ field })`,
-     * values are Zod schemas with `.describe()`.
-     *
-     * The state definition serves two purposes:
-     * 1. Type inference — `TState` is automatically derived, no explicit generic needed
-     * 2. AI protocol — field names, types, and descriptions are included in the tool
-     *    description so the AI can pre-fill answers via `_meta.flow.state`
-     *
-     * @example
-     * ```ts
-     * state: {
-     *   country: z.string().describe("Country the business is based in"),
-     *   status: z.enum(["registered", "unregistered"]).describe("Business registration status"),
-     * }
-     * ```
-     */
-    state: Record<string, z.ZodType>;
+type DeviceType = "mobile" | "tablet" | "desktop" | "unknown";
+type UserAgent = {
+    device: {
+        type: DeviceType;
+    };
+    capabilities: {
+        hover: boolean;
+        touch: boolean;
+    };
+};
+/** Display mode */
+type DisplayMode = "pip" | "inline" | "fullscreen";
+type RequestDisplayMode = (args: {
+    mode: DisplayMode;
+}) => Promise<{
     /**
-     * If true, instruct the agent to omit PII (names, emails, phones, addresses,
-     * IDs, ages, birthdates) from the `intent` and `context` fields. Only adds a
-     * guidance line to the tool description — does not redact server-side.
+     * The granted display mode. The host may reject the request.
+     * For mobile, PiP is always coerced to fullscreen.
      */
-    omitIntentPII?: boolean;
-    /** Optional tool annotations */
-    annotations?: {
-        readOnlyHint?: boolean;
-        idempotentHint?: boolean;
-        openWorldHint?: boolean;
-        destructiveHint?: boolean;
-    };
+    mode: DisplayMode;
+}>;
+type CallToolResponse = {
+    result: string;
 };
+/** Calling APIs */
+type CallTool = (name: string, args: Record<string, unknown>) => Promise<CallToolResponse>;
+/** Extra events */
+declare const SET_GLOBALS_EVENT_TYPE = "openai:set_globals";
+declare class SetGlobalsEvent extends CustomEvent<{
+    globals: Partial<OpenAIGlobals>;
+}> {
+    constructor(detail: {
+        globals: Partial<OpenAIGlobals>;
+    });
+}
+/**
+ * Global oai object injected by the web sandbox for communicating with chatgpt host page.
+ */
+declare global {
+    interface Window {
+        openai: API & OpenAIGlobals;
+        innerBaseUrl: string;
+    }
+    interface WindowEventMap {
+        [SET_GLOBALS_EVENT_TYPE]: SetGlobalsEvent;
+    }
+}
+
 /**
- * Infer the runtime state type from a flow's state schema definition.
- *
- * @example
- * ```ts
- * const config = {
- *   state: {
- *     country: z.enum(["FR", "DE"]),
- *     status: z.enum(["registered", "unregistered"]),
- *   }
- * };
- * type MyState = InferFlowState<typeof config.state>;
- * // { country: "FR" | "DE"; status: "registered" | "unregistered" }
- * ```
+ * Result from calling a tool
  */
-type InferFlowState<T extends Record<string, z.ZodType>> = {
-    [K in keyof T]: z.infer<T[K]>;
-};
+type ToolCallResult = CallToolResult;
 /**
- * Flow tool handler — uses shared MCP types (`RequestHandlerExtra`, `CallToolResult`)
- * so it's assignable to both MCP SDK's `ToolCallback` and Skybridge's `ToolHandler`.
+ * Tool result notification (what the host pushes to the widget)
  */
-type FlowToolHandler = (args: Record<string, unknown>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => CallToolResult | Promise<CallToolResult>;
+type ToolResult = CallToolResult;
 /**
- * A compiled flow — can be registered on an McpServer.
- *
- * Exposes MCP-compatible `name`, `config`, and `handler` so it can be
- * registered directly: `server.registerTool(flow.name, flow.config, flow.handler)`
+ * Host context - all values available from the host.
  */
-type RegisteredFlow = {
-    /** Tool name — pass to `server.registerTool(flow.name, flow.config, flow.handler)`. */
-    name: string;
-    /** Tool config object — pass to `server.registerTool(flow.name, flow.config, flow.handler)`. */
-    config: {
-        title: string;
-        description: string;
-        inputSchema: ZodRawShapeCompat;
-        annotations?: {
-            readOnlyHint?: boolean;
-            idempotentHint?: boolean;
-            openWorldHint?: boolean;
-            destructiveHint?: boolean;
-        };
-    };
-    /** Tool callback — pass to `server.registerTool(flow.name, flow.config, flow.handler)`. */
-    handler: FlowToolHandler;
-    /** Register this flow on an MCP server. Shorthand for `server.registerTool(flow.name, flow.config, flow.handler)`. */
-    register: (server: McpServer) => Promise<void>;
-    /** Returns a Mermaid `flowchart TD` diagram of the flow graph. */
-    graph: () => string;
-    flowGraph: FlowGraph;
-};
-type FlowTokenContent = {
-    step?: string;
-    state: Record<string, unknown>;
-    field?: string;
-    widgetId?: string;
-};
-type InterruptQuestionData = {
-    question: string;
-    field: string;
-    suggestions?: string[];
-    context?: string;
-};
-type FlowInterruptContent = {
-    status: "interrupt";
-    /** Single-question shorthand */
-    question?: string;
-    field?: string;
-    suggestions?: string[];
-    /** Multi-question */
-    questions?: InterruptQuestionData[];
-    context?: string;
-};
-type FlowWidgetContent = {
-    status: "widget";
-    /** Display tool to call */
-    tool: string;
-    /** Data to pass to the display tool */
-    data: Record<string, unknown>;
-    description?: string;
-    /** Whether the widget expects user interaction before continuing */
-    interactive?: boolean;
-};
-type FlowCompleteContent = {
-    status: "complete";
-};
-type FlowErrorContent = {
-    status: "error";
-    error: string;
+type HostContext = {
+    theme: Theme;
+    locale: string;
+    displayMode: DisplayMode;
+    maxHeight: number | null;
+    safeArea: SafeArea | null;
+    toolOutput: UnknownObject | null;
+    toolResponseMetadata: UnknownObject | null;
+    widgetState: UnknownObject | null;
 };
-
 /**
- * A LangGraph-inspired state graph builder for MCP tools.
+ * Unified widget client interface that works on both OpenAI and MCP Apps.
  *
- * @example
- * ```ts
- * const flow = new StateGraph<MyState>({
- *   id: "onboarding",
- *   title: "User Onboarding",
- *   description: "Guides users through onboarding",
- * })
- *   .addNode("ask_name", ({ interrupt }) => interrupt({ question: "What's your name?", field: "name" }))
- *   .addNode("greet", ({ state }) => ({ greeting: `Hello ${state.name}!` }))
- *   .addEdge(START, "ask_name")
- *   .addEdge("ask_name", "greet")
- *   .addEdge("greet", END)
- *   .compile();
- * ```
+ * Platform-specific behavior:
+ * - Display mode: OpenAI-only. MCP Apps returns "inline" and requestDisplayMode is a no-op.
+ * - Follow-up messages: Unified API, different underlying implementations.
  */
-declare class StateGraph<TState extends Record<string, unknown>, TNodes extends string = never> {
-    private nodes;
-    private edges;
-    private nodeOptions;
-    private config;
-    constructor(config: FlowConfig);
+interface UnifiedWidgetClient {
     /**
-     * Add a node with a handler.
-     *
-     * The handler receives a context object with `state`, `meta`, `interrupt`, and `showWidget`.
+     * Connect to the host. Must be called before using other methods.
+     * On OpenAI, this is a no-op (already connected via window.openai).
+     * On MCP Apps, this establishes the postMessage connection.
      */
-    addNode<TName extends string>(name: TName, handler: NodeHandler<TState>, options?: NodeOptions): StateGraph<TState, TNodes | TName>;
+    connect(): Promise<void>;
     /**
-     * Add a direct edge between two nodes.
-     *
-     * Use `START` as `from` to set the entry point.
-     * Use `END` as `to` to mark a terminal node.
+     * Close the connection to the host and clean up resources.
+     * On OpenAI, this is a no-op.
+     * On MCP Apps, this closes the transport and removes event listeners.
      */
-    addEdge(from: typeof START | TNodes, to: TNodes | typeof END): this;
+    close(): Promise<void>;
     /**
-     * Add a conditional edge from a node.
-     *
-     * The condition function receives current state and returns the name of the next node.
+     * Get the tool output (structured content returned by the tool handler).
+     * This is the main data source for widget rendering.
      */
-    addConditionalEdge(from: TNodes, condition: (state: Partial<TState>) => TNodes | typeof END | Promise<TNodes | typeof END>): this;
+    getToolOutput<T = Record<string, unknown>>(): T | null;
     /**
-     * Generate a Mermaid `flowchart TD` diagram of the graph.
-     *
-     * Direct edges use solid arrows. Conditional edges use a dashed arrow
-     * to a placeholder since branch targets are determined at runtime.
-     *
-     * @example
-     * ```ts
-     * console.log(graph.graph());
-     * // flowchart TD
-     * //   __start__((Start))
-     * //   ask_name[ask_name]
-     * //   greet[greet]
-     * //   __end__((End))
-     * //   __start__ --> ask_name
-     * //   ask_name --> greet
-     * //   greet --> __end__
-     * ```
+     * Register a callback for when tool results are received.
+     * On OpenAI, this subscribes to toolOutput changes.
+     * On MCP Apps, this sets app.ontoolresult.
+     */
+    onToolResult(callback: (result: ToolResult) => void): () => void;
+    /**
+     * Call another tool on the server.
+     */
+    callTool(name: string, args: Record<string, unknown>): Promise<ToolCallResult>;
+    /**
+     * Open an external URL.
+     * On OpenAI: openai.openExternal({ href })
+     * On MCP Apps: app.sendOpenLink(url)
+     */
+    openExternal(url: string): void;
+    /**
+     * Send a follow-up message to the AI.
+     * On OpenAI: openai.sendFollowUpMessage({ prompt })
+     * On MCP Apps: app.sendMessages([{ role: 'user', content: { type: 'text', text: prompt } }])
+     */
+    sendFollowUp(prompt: string): void | Promise<void>;
+    /**
+     * Update hidden model context for the next assistant turn.
+     * On MCP Apps this uses the standard `ui/update-model-context` request.
+     * On other hosts this may fall back to best-effort behavior.
+     */
+    updateModelContext(context: ModelContextUpdate): Promise<void> | void;
+    /**
+     * Get the current theme.
+     */
+    getTheme(): Theme;
+    /**
+     * Subscribe to theme changes.
+     */
+    onThemeChange(callback: (theme: Theme) => void): () => void;
+    /**
+     * Get the current locale.
+     */
+    getLocale(): string;
+    /**
+     * Get the current display mode.
+     * OpenAI-only: returns "pip" | "inline" | "fullscreen"
+     * MCP Apps: always returns "inline"
+     */
+    getDisplayMode(): DisplayMode;
+    /**
+     * Request a display mode change.
+     * OpenAI-only: requests the mode from the host.
+     * MCP Apps: no-op (returns current mode).
+     */
+    requestDisplayMode(mode: DisplayMode): Promise<DisplayMode>;
+    /**
+     * Subscribe to display mode changes.
+     * OpenAI-only: subscribes to displayMode changes.
+     * MCP Apps: callback is never called.
+     */
+    onDisplayModeChange(callback: (mode: DisplayMode) => void): () => void;
+    /**
+     * Get the safe area insets.
+     * OpenAI-only: returns insets from window.openai.safeArea.
+     * MCP Apps: returns null.
+     */
+    getSafeArea(): SafeArea | null;
+    /**
+     * Subscribe to safe area changes.
+     * OpenAI-only: subscribes to safeArea changes.
+     * MCP Apps: callback is never called.
+     */
+    onSafeAreaChange(callback: (safeArea: SafeArea | null) => void): () => void;
+    /**
+     * Get the max height constraint.
+     * OpenAI-only: returns maxHeight from window.openai.maxHeight.
+     * MCP Apps: returns null.
+     */
+    getMaxHeight(): number | null;
+    /**
+     * Subscribe to max height changes.
+     * OpenAI-only: subscribes to maxHeight changes.
+     * MCP Apps: callback is never called.
+     */
+    onMaxHeightChange(callback: (maxHeight: number | null) => void): () => void;
+    /**
+     * Get the tool response metadata.
+     * OpenAI: returns metadata from window.openai.toolResponseMetadata.
+     * MCP Apps: returns `_meta` from the latest `ui/notifications/tool-result`, if provided by host.
      */
-    graph(): string;
+    getToolResponseMetadata(): UnknownObject | null;
     /**
-     * Compile the graph into a RegisteredFlow that can be registered on an McpServer.
-     *
-     * Validates the graph structure and returns a registration-compatible object.
+     * Subscribe to tool response metadata changes.
+     * OpenAI: subscribes to toolResponseMetadata changes.
+     * MCP Apps: fires when tool result `_meta` changes.
      */
-    compile(options?: {
-        store?: FlowStore;
-    }): RegisteredFlow;
-    private validate;
-}
-
-/**
- * Create a new flow graph — convenience factory for `new StateGraph()`.
- *
- * The state type is automatically inferred from the `state` definition —
- * no explicit generic parameter needed.
- *
- * @example
- * ```ts
- * import { createFlow, interrupt, START, END } from "@waniwani/sdk/mcp";
- * import { z } from "zod";
- *
- * const flow = createFlow({
- *   id: "onboarding",
- *   title: "User Onboarding",
- *   description: "Guides users through onboarding. Use when a user wants to get started.",
- *   state: {
- *     name: z.string().describe("The user's name"),
- *     email: z.string().describe("The user's email address"),
- *   },
- * })
- *   .addNode("ask_name", () => interrupt({ question: "What's your name?", field: "name" }))
- *   .addNode("ask_email", () => interrupt({ question: "What's your email?", field: "email" }))
- *   .addEdge(START, "ask_name")
- *   .addEdge("ask_name", "ask_email")
- *   .addEdge("ask_email", END)
- *   .compile();
- * ```
- */
-declare function createFlow<const TSchema extends Record<string, z.ZodType>>(config: Omit<FlowConfig, "state"> & {
-    state: TSchema;
-}): StateGraph<InferFlowState<TSchema>>;
-
-/**
- * Mark a Zod schema as PII — its value will be replaced with `"REDACTED"` in
- * any `tool.called` event payload sent to the WaniWani API. The handler still
- * receives the original value; only the tracked copy is scrubbed.
- *
- * Apply at the end of the schema chain so the marker is attached to the final
- * schema:
- *
- * ```ts
- * ages: redacted(z.string().describe("Comma-separated ages")),
- * zipcode: redacted(z.string().describe("Spanish postal code")),
- * ```
- *
- * Uses Zod v4's `.meta()` registry, so the marker is preserved across schema
- * clones (`.optional()`, `.default()`, etc.).
- */
-declare function redacted<T extends z.ZodType>(schema: T): T;
-
-type WithDecodedState = {
-    decodedState: FlowTokenContent | null;
-};
-type FlowTestResult = (FlowInterruptContent & WithDecodedState) | (FlowWidgetContent & WithDecodedState) | (FlowCompleteContent & WithDecodedState) | (FlowErrorContent & WithDecodedState);
-declare function createFlowTestHarness(flow: RegisteredFlow, options?: {
-    stateStore?: FlowStore;
-}): Promise<{
-    start(intent: string, stateUpdates?: Record<string, unknown>, context?: string): Promise<FlowTestResult>;
-    continueWith(stateUpdates?: Record<string, unknown>): Promise<FlowTestResult>;
-    resetWith(stateUpdates: Record<string, unknown>): Promise<FlowTestResult>;
-    lastState(): Promise<FlowTokenContent | null>;
-}>;
-
-/**
- * Generic key-value store backed by the WaniWani API.
- *
- * Values are stored as JSON objects (`Record<string, unknown>`) in the
- * `/api/mcp/redis/*` endpoints. Tenant isolation is handled by the API key.
- *
- * Config is read from env vars:
- * - `WANIWANI_API_KEY` (required)
- * - `WANIWANI_API_URL` (optional, defaults to https://app.waniwani.ai)
- * - `WANIWANI_ENCRYPTION_KEY` (optional, base64-encoded 32-byte key for AES-256-GCM encryption)
- */
-interface KvStore<T = Record<string, unknown>> {
-    get(key: string): Promise<T | null>;
-    set(key: string, value: T): Promise<void>;
-    delete(key: string): Promise<void>;
-}
-declare class WaniwaniKvStore<T = Record<string, unknown>> implements KvStore<T> {
-    private get baseUrl();
-    private get apiKey();
-    private get encryptionKey();
-    get(key: string): Promise<T | null>;
-    set(key: string, value: T): Promise<void>;
-    delete(key: string): Promise<void>;
-    private request;
+    onToolResponseMetadataChange(callback: (metadata: UnknownObject | null) => void): () => void;
+    /**
+     * Get the widget state.
+     * OpenAI-only: returns state from window.openai.widgetState.
+     * MCP Apps: returns null.
+     */
+    getWidgetState(): UnknownObject | null;
+    /**
+     * Subscribe to widget state changes.
+     * OpenAI-only: subscribes to widgetState changes.
+     * MCP Apps: callback is never called.
+     */
+    onWidgetStateChange(callback: (state: UnknownObject | null) => void): () => void;
 }
 
 /**
  * Creates a reusable UI resource (HTML template) that can be attached
  * to tools or flow nodes.
  *
+ * @deprecated Prefer `createFlow` with `showWidget` from `@waniwani/sdk/mcp` for new code.
+ *   `createResource` is preserved for back-compat with existing customer MCPs but is no longer
+ *   documented; it will move to `@waniwani/sdk/legacy` in a future minor release.
+ *
  * @example
  * ```ts
  * const pricingUI = createResource({
@@ -1096,6 +1305,10 @@ declare function createResource(config: ResourceConfig): RegisteredResource;
  * When `handler()` returns `data`, the tool includes it as MCP `structuredContent`.
  * When `config.resource` is provided, the tool also returns widget metadata.
  *
+ * @deprecated Prefer `createFlow` from `@waniwani/sdk/mcp` for new code. `createTool`
+ *   is preserved for back-compat with existing customer MCPs but is no longer documented;
+ *   it will move to `@waniwani/sdk/legacy` in a future minor release.
+ *
  * @example
  * ```ts
  * // Widget tool (with resource)
@@ -1121,146 +1334,11 @@ declare function createResource(config: ResourceConfig): RegisteredResource;
  */
 declare function createTool<TInput extends z.ZodRawShape>(config: ToolConfig<TInput>, handler: ToolHandler<TInput>): RegisteredTool;
 /**
- * Registers multiple tools on the server
- */
-declare function registerTools(server: McpServer, tools: RegisteredTool[]): Promise<void>;
-
-/**
- * Server-side API route handler for widget tracking events.
- *
- * Receives batched events from the `useWaniwani` React hook and forwards them
- * to the WaniWani backend using the server-side SDK.
- *
- * @example Next.js App Router
- * ```typescript
- * // app/api/waniwani/track/route.ts
- * import { createTrackingRoute } from "@waniwani/sdk/mcp";
- *
- * const handler = createTrackingRoute({
- *   apiKey: process.env.WANIWANI_API_KEY,
- *   apiUrl: process.env.WANIWANI_API_URL,
- * });
- *
- * export { handler as POST };
- * ```
- */
-interface TrackingRouteOptions {
-    /** API key for the WaniWani backend. Defaults to WANIWANI_API_KEY env var. */
-    apiKey?: string;
-    /** Base URL for the WaniWani backend. Defaults to https://app.waniwani.ai. */
-    apiUrl?: string;
-}
-/**
- * Creates a POST handler that receives tracking events from `useWaniwani`
- * and forwards them to the WaniWani backend.
- */
-declare function createTrackingRoute(options?: TrackingRouteOptions): (request: Request) => Promise<Response>;
-
-/**
- * WaniWani SDK Client
- *
- * Extends with each module:
- * - TrackingClient: track(), flush(), shutdown()
- *
- * Pass this client to framework adapters:
- * - `toNextJsHandler(wani, { ... })` for Next.js route handlers
- */
-interface WaniWaniClient extends TrackingClient {
-    /** @internal Resolved config — used by framework adapters */
-    readonly _config: InternalConfig;
-    /** Knowledge base client for ingestion, search, and source listing */
-    readonly kb: KbClient;
-}
-interface InternalConfig {
-    apiUrl: string;
-    apiKey: string | undefined;
-    tracking: Required<TrackingConfig>;
-}
-
-type WaniwaniTracker = Pick<WaniWaniClient, "flush" | "track" | "identify" | "kb" | "_config">;
-
-type UnknownRecord = Record<string, unknown>;
-/**
- * Options for withWaniwani().
- */
-type WithWaniwaniOptions = {
-    /**
-     * The WaniWani client instance. When omitted, a client is created
-     * automatically using the global config registered by `defineConfig()`,
-     * falling back to env vars.
-     */
-    client?: WaniwaniTracker;
-    /**
-     * Optional explicit tool type. Defaults to `"other"`.
-     */
-    toolType?: ToolCalledProperties["type"] | ((toolName: string) => ToolCalledProperties["type"] | undefined);
-    /**
-     * Optional metadata merged into every tracked event.
-     */
-    metadata?: UnknownRecord;
-    /**
-     * Flush tracking transport after each tool call.
-     */
-    flushAfterToolCall?: boolean;
-    /**
-     * Optional error callback for non-fatal tracking errors.
-     */
-    onError?: (error: Error) => void;
-    /**
-     * Inject widget tracking config into tool response `_meta.waniwani` so browser
-     * widgets can send events directly to the WaniWani backend.
-     *
-     * Always injects `endpoint`. Injects `token` when an API key is configured
-     * and token minting succeeds.
-     *
-     * @default true
-     */
-    injectWidgetToken?: boolean;
-    /**
-     * List of field names to strip from known location `_meta` entries
-     * (`openai/userLocation`, `waniwani/geoLocation`, `waniwani/userLocation`)
-     * before events are sent to the WaniWani API. Applied to both the
-     * request-level `_meta` and any `_meta` on the tool response.
-     *
-     * Pass e.g. `["latitude", "longitude"]` to drop coordinates only, or
-     * `["latitude", "longitude", "city", "region"]` to keep just `country`.
-     * Empty/omitted = no redaction.
-     *
-     * @default []
-     */
-    stripLocationFields?: readonly string[];
-    /**
-     * Replace `input.stateUpdates[field]` with `"REDACTED"` for any field
-     * marked via `redacted()` on a flow state schema. When `false` (default),
-     * the declarative markers are ignored and raw values are tracked.
-     *
-     * Wire this to an env var when you want real values in development logs
-     * but redacted values in production.
-     *
-     * @default false
-     */
-    applyFieldRedactions?: boolean;
-};
-/**
- * Wrap an MCP server so tool handlers automatically emit `tool.called` events.
- *
- * The wrapper intercepts `server.registerTool(...)` for future registrations
- * and also walks `server._registeredTools` to wrap any tools already registered
- * at the time of the call. This means either call order works:
- *
- *   withWaniwani(server); server.registerTool(...);   // wrap then register
- *   server.registerTool(...); withWaniwani(server);   // register then wrap
- *
- * When `injectWidgetToken` is enabled (default), tracking config is injected
- * into tool response `_meta.waniwani` so browser widgets can post events
- * directly to the WaniWani backend without a server-side proxy.
+ * Registers multiple tools on the server.
  *
- * Widget metadata declared on the tool **definition** (e.g. skybridge's
- * `registerWidget`, raw MCP `_meta["ui/resourceUri"]` / `_meta.ui.resourceUri`,
- * OpenAI's `_meta["openai/outputTemplate"]`) is also forwarded into each tool
- * result's `_meta`, so chat UIs that only see tool results (and not
- * `tools/list`) can still render widgets. Handler-set keys take precedence.
+ * @deprecated Prefer `createFlow` + `.register()` for new code. Preserved for back-compat
+ *   with existing customer MCPs; will move to `@waniwani/sdk/legacy` in a future minor release.
  */
-declare function withWaniwani(server: McpServer, options?: WithWaniwaniOptions): Promise<McpServer>;
+declare function registerTools(server: McpServer, tools: RegisteredTool[]): Promise<void>;
 
-export { type ConditionFn, END, type FlowConfig, type FlowTestResult, type HostContext, type InferFlowState, type InterruptSignal, type KvStore, type NodeContext, type NodeHandler, type RegisteredFlow, type RegisteredResource, type RegisteredTool, type ResourceConfig, START, type ScopedWaniWaniClient, StateGraph, type ToolCallResult, type ToolConfig, type ToolHandler, type ToolHandlerContext, type ToolResult, type ToolToolCallback, type TrackingRouteOptions, type TypedInterrupt, type TypedShowWidget, type UnifiedWidgetClient, WaniwaniKvStore, type WidgetCSP, type WidgetPlatform, type WidgetSignal, type WithWaniwaniOptions, createFlow, createFlowTestHarness, createResource, createTool, createTrackingRoute, detectPlatform, isMCPApps, isOpenAI, redacted, registerTools, withWaniwani };
+export { type AddNodeConfig, type ConditionFn, END, type FlowConfig, type FlowTestResult, type HostContext, type InferFlowState, type InterruptSignal, type KvStore, MemoryKvStore, type NodeContext, type NodeHandler, type RegisteredFlow, type RegisteredResource, type RegisteredTool, type ResourceConfig, START, type ScopedWaniWaniClient, StateGraph, type ToolCallResult, type ToolConfig, type ToolHandler, type ToolHandlerContext, type ToolResult, type ToolToolCallback, type TrackingRouteOptions, type TypedInterrupt, type TypedShowWidget, type UnifiedWidgetClient, WaniwaniKvStore, type WidgetCSP, type WidgetPlatform, type WidgetSignal, type WithWaniwaniOptions, createFlow, createFlowTestHarness, createResource, createTool, createTrackingRoute, detectPlatform, isMCPApps, isOpenAI, redacted, registerTools, withWaniwani };