@waniwani/sdk 0.20.0 → 0.20.2

package/dist/mcp/index.d.ts

@@ -6,6 +6,325 @@ import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
+/**
+ * Reading a widget's view binding off MCP `_meta`.
+ *
+ * Kept in `shared/` because three surfaces ask the same question and none of
+ * them should own the answer: the chat resolves a tool part's view before
+ * rendering it, the WebMCP endpoint resolves a display tool's view before
+ * handing it to the page, and both have to agree or a widget renders in one
+ * place and not the other.
+ *
+ * The three spellings below are not alternatives to choose between. They are
+ * what three host generations actually emit, and a server built on any of them
+ * is a server we have to render.
+ */
+/** Anything carrying MCP `_meta`: a tool definition, a tool result, a resource. */
+type MetaCarrier = {
+    _meta?: Record<string, unknown>;
+};
+/**
+ * The view a `_meta` binds to, checking all three shapes in priority order:
+ *
+ * 1. `_meta.ui.resourceUri` — MCP Apps, nested (skybridge, ext-apps)
+ * 2. `_meta["ui/resourceUri"]` — MCP Apps, flat (earlier drafts, still in the wild)
+ * 3. `_meta["openai/outputTemplate"]` — OpenAI Apps SDK
+ *
+ * Order is priority, not preference: a server emitting more than one emits them
+ * as aliases of the same view, and the nested form is the one the current spec
+ * defines.
+ */
+declare function resourceUriFromMeta(meta: Record<string, unknown> | undefined): string | undefined;
+/** Whether the host should size the frame from the view's content. */
+declare function autoHeightFromMeta(meta: Record<string, unknown> | undefined): boolean;
+/**
+ * The view a tool renders, read from its definition.
+ *
+ * Definition rather than result on purpose. A spec-compliant server binds the
+ * view on the tool, so a result carries the binding only by accident, and
+ * reading the result first means a tool whose view is declared correctly looks
+ * like a tool with no view at all.
+ */
+declare function viewUriFor(tool: MetaCarrier | undefined): string | undefined;
+/**
+ * Whether a tool exists to render something rather than to be reasoned about.
+ *
+ * The distinction matters wherever a tool list crosses a boundary. A display
+ * tool advertised to a browsing agent is a tool it will try to call to make a
+ * widget appear, on a surface with no widget host in it, which burns a turn and
+ * strands the conversation on a render nobody performs.
+ */
+declare function isDisplayTool(tool: MetaCarrier | undefined): boolean;
+
+/**
+ * The shapes crossing the WebMCP boundary.
+ *
+ * Structural rather than imported from `@modelcontextprotocol/sdk`, because
+ * everything here is also read by the browser bridge, and the MCP SDK is an
+ * optional peer dependency that has no business in a page bundle. What the
+ * server sends and what the page reads is JSON either way.
+ */
+/**
+ * One MCP content block. `type` is the discriminator every block carries; the
+ * index signature keeps the rest of whichever block it is, since nothing on
+ * this path reads them and re-deriving the union would only restate a schema
+ * the server already validated on the way out.
+ */
+type WebMcpContentBlock = {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+};
+/** A tool as `tools/list` describes it. */
+type WebMcpTool = {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    annotations?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+};
+/** A tool result as `tools/call` returns it. */
+type WebMcpCallResult = {
+    content?: WebMcpContentBlock[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+};
+/**
+ * Everything the page needs to mount a widget itself.
+ *
+ * Assembled server-side because none of it is derivable on the page: the view
+ * URI carries a content hash that moves every deploy, and the display tool's
+ * result is what the view reads its own configuration from.
+ */
+type WebMcpWidgetPayload = {
+    /**
+     * The `ui://` the view was resolved from.
+     *
+     * Carries a content hash that moves on every deploy, which is why this is
+     * resolved server-side per call and why nothing on the page can cache it.
+     *
+     * The only half of the view the page is told. Where to fetch it from is the
+     * resource endpoint the page already derived from its token, the same one
+     * the chat's own widget iframes use.
+     */
+    viewUri: string;
+    /** Display tool the view belongs to. */
+    tool: string;
+    /** Props, delivered to the view as `ui/notifications/tool-input`. */
+    data: Record<string, unknown>;
+    /** The display tool's own result, delivered as `ui/notifications/tool-result`. */
+    result: {
+        content: WebMcpContentBlock[];
+        structuredContent?: Record<string, unknown>;
+        _meta?: Record<string, unknown>;
+    };
+    /** Whether the flow is waiting on the visitor before it can advance. */
+    interactive: boolean;
+    /**
+     * Set by the preview endpoint. A real widget step is a flow waiting on the
+     * visitor and has no way out; a preview is something someone opened to look
+     * at, so the host can give it one.
+     */
+    preview?: boolean;
+};
+/** What every page-facing request carries, whatever it is asking for. */
+type WebMcpRequestBase = {
+    /**
+     * Tab-scoped, and the key the flow engine stores its state under.
+     *
+     * Must be stable for the tab and must not outlive it. A value that changes
+     * between calls silently restarts every flow; one that persists across days
+     * resumes a flow abandoned last week mid-question.
+     */
+    sessionId: string;
+    /**
+     * The visitor's persistent id. Identity rather than state, and what lets a
+     * flow started here and a conversation continued in the chat bubble belong
+     * to one person.
+     */
+    visitorId?: string;
+    /**
+     * The channel this page's embed belongs to.
+     *
+     * Sent because ingest rejects events it cannot attribute to a channel, and a
+     * token-only embed learns its channel from `/config` rather than from its
+     * own markup. Without it a tool call is attributed to nothing and the events
+     * behind it are dropped.
+     */
+    channelId?: string;
+    /** Where the visitor was standing when the agent called. */
+    page?: WebMcpPageContext;
+};
+/**
+ * `POST` body for the page-facing tools endpoint.
+ *
+ * The bridge builds exactly this, so a server implementing the other end is
+ * type-checked against what actually arrives rather than against a description
+ * of it.
+ */
+type WebMcpRequest = (WebMcpRequestBase & {
+    action: "list";
+}) | (WebMcpRequestBase & {
+    action: "call";
+    name: string;
+    arguments?: Record<string, unknown>;
+});
+/** Where the visitor was standing when the agent called. */
+type WebMcpPageContext = {
+    url?: string;
+    title?: string;
+};
+type WebMcpListResponse = {
+    tools: WebMcpTool[];
+};
+type WebMcpCallResponse = {
+    content: WebMcpContentBlock[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+    /** Present and non-null only when the call produced a resolvable widget step. */
+    widget: WebMcpWidgetPayload | null;
+};
+
+/**
+ * The WebMCP bridge.
+ *
+ * A browsing agent standing on a page never speaks to the MCP server. It speaks
+ * to the page, through `document.modelContext`, and this is what puts the
+ * server's tools there. Every `execute()` the agent calls lands on the endpoint
+ * below, which stamps attribution server-side and answers.
+ *
+ * Nothing here discovers its own configuration. The endpoint, both ids, and the
+ * widget callback are arguments, because there are two callers with two
+ * different ways of knowing them: the chat embed reads them from its remote
+ * config, and the standalone loader derives them from its own script tag.
+ * Sniffing `document.currentScript` inside a bundle that may be loaded twenty
+ * modules deep finds the wrong script or none.
+ */
+
+type WebMcpBridgeOptions = {
+    /** Absolute URL of the server's page-facing tools endpoint. */
+    endpoint: string;
+    /**
+     * Extra request headers, merged over `content-type`.
+     *
+     * The hosted API authenticates with `Authorization: Bearer <public token>`
+     * here, the same as every other call the embed makes. A self-hosted server
+     * reached directly needs none.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Tab-scoped id, and the key the flow engine stores its state under.
+     *
+     * Must be stable for the tab and must not outlive it. A value that changes
+     * between calls silently restarts every flow; a value that persists across
+     * days resumes a flow abandoned last week mid-question.
+     */
+    sessionId: string;
+    /**
+     * The visitor's persistent id, from `shared/visitor-id`.
+     *
+     * Identity rather than state. Sending it is what lets a flow started here
+     * and a conversation continued in the chat bubble belong to one person.
+     */
+    visitorId?: string;
+    /**
+     * The channel this embed belongs to, from the script tag or `/config`.
+     *
+     * Ingest drops events it cannot attribute to a channel, so a tool call sent
+     * without this produces conversions nobody can see.
+     */
+    channelId?: string;
+    /**
+     * Called when a tool call resolves to a widget the page should mount.
+     *
+     * Optional, and the surface works without it: everything the visitor needs
+     * is also in the text the agent receives. A page with no host gets a flow
+     * carried in words.
+     */
+    onWidget?: (widget: WebMcpWidgetPayload) => void;
+    /** Defaults to `console`. */
+    logger?: Pick<Console, "error" | "info">;
+};
+/** Live for as long as the bridge is registered. */
+type WebMcpBridge = {
+    /** Tools successfully registered with the browser. */
+    readonly tools: WebMcpTool[];
+    /** Unregister everything. Idempotent. */
+    dispose: () => void;
+};
+/** Whether this browser can host site tools at all. Almost every visit: no. */
+declare function supportsWebMcp(): boolean;
+/**
+ * Register the server's tools with the browsing agent.
+ *
+ * Resolves once registration has been attempted for every advertised tool. A
+ * tool the browser refuses is logged and skipped rather than failing the rest,
+ * because a partial tool list is a working page and an exception here is a
+ * blank one.
+ *
+ * Returns `null` when the browser has no `modelContext`, which is the common
+ * case and not an error.
+ */
+declare function createWebMcpBridge(options: WebMcpBridgeOptions): Promise<WebMcpBridge | null>;
+
+/**
+ * Structural stand-in for a Zod schema, so the package root's type graph does
+ * not reference `zod`, an optional peer. Pass a real Zod schema: `extract()`
+ * converts it with `z.toJSONSchema()`, which no other `parse`-shaped object
+ * survives.
+ */
+interface DocumentSchema<T> {
+    parse(value: unknown): T;
+}
+interface DocumentExtractResult<T> {
+    /** The document's contents, parsed with the schema you passed. A null field is one the document did not legibly answer. */
+    fields: T;
+    /** Pages the vendor processed and billed */
+    pageCount: number;
+    /** Mean per-page OCR confidence, null when none was reported */
+    pageConfidence: number | null;
+    /** Handle for this extraction, valid for the 7-day retention window */
+    documentId: string;
+}
+/** A document the visitor uploaded through the chat widget, already stored by the platform. */
+interface AttachedDocument {
+    /** Pass to `documents.extract({ documentId, schema })` to read it. */
+    documentId: string;
+    /** Name the visitor's file had */
+    filename: string;
+    /** MIME type the browser declared on upload */
+    mediaType: string;
+}
+interface DocumentExtractCommon<T> {
+    /** The shape to return. Extraction runs in strict mode, so mark anything a document may not answer `.nullable()`. */
+    schema: DocumentSchema<T>;
+    /** Zero-based page indexes to read: `[0]` is the first page. Omit to read every page. Ignored for images. Billing is per page processed, so a narrower selection costs less. */
+    pages?: number[];
+    /** Conversation this document arrived in */
+    sessionId?: string;
+    /** Ties the extraction to one tool call */
+    correlationId?: string;
+}
+/** Read a document the platform has never seen, by fetching it. */
+interface DocumentExtractUrlInput<T> extends DocumentExtractCommon<T> {
+    /** A publicly fetchable URL; private and loopback addresses are refused */
+    url: string;
+    /** Name of the file, used to refuse an unsupported type before fetching it */
+    filename: string;
+    documentId?: never;
+}
+/** Read a document the platform already holds, uploaded by a visitor through the chat widget. */
+interface DocumentExtractStoredInput<T> extends DocumentExtractCommon<T> {
+    /** From `context.waniwani.attachedDocuments`, or `readAttachedDocuments()` on your own chat route. The platform kept the filename, so there is none to pass. */
+    documentId: string;
+}
+type DocumentExtractInput<T> = DocumentExtractUrlInput<T> | DocumentExtractStoredInput<T>;
+interface DocumentsClient {
+    /** Read one document and get its contents shaped by `schema`. Accepts PDF, PNG, JPEG, TIFF, BMP, GIF and WEBP up to 50 MB. */
+    extract<T>(input: DocumentExtractInput<T>): Promise<DocumentExtractResult<T>>;
+}
+
 interface SearchResult {
     source: string;
     heading: string;
@@ -351,6 +670,12 @@ interface TrackingClient {
     shutdown: (options?: TrackingShutdownOptions) => Promise<TrackingShutdownResult>;
 }
 
+/** A file the host bound to this tool call, resolved to something fetchable. */
+interface AttachedFile {
+    url: string;
+    filename: string;
+}
+
 /**
  * Well-known key used to attach the scoped client to the MCP `extra` object.
  * Read by `createTool` and flow compilation to surface it in handler contexts.
@@ -397,6 +722,21 @@ interface ScopedWaniWaniClient {
     }>;
     /** Knowledge base client (no meta needed). */
     readonly kb: KbClient;
+    /**
+     * Files the host attached to this tool call, each with a fetchable `url` and
+     * a `filename` — spread one straight into `documents.extract()`. Empty on
+     * hosts that attach nothing.
+     */
+    readonly attachedFiles: AttachedFile[];
+    /**
+     * Documents the visitor uploaded through the chat widget on this turn. The
+     * platform holds the bytes, so each entry is a handle: spread one straight
+     * into `documents.extract({ documentId, schema })`. Empty on hosts that
+     * upload nothing.
+     */
+    readonly attachedDocuments: AttachedDocument[];
+    /** Documents client; `sessionId` and `correlationId` are carried from the request. */
+    readonly documents: DocumentsClient;
     /** @internal Resolved API config from withWaniwani(). */
     readonly _config?: {
         apiUrl?: string;
@@ -489,6 +829,10 @@ interface FlowStore {
 }
 
 declare const flowOutputSchema: {
+    intro: z.ZodOptional<z.ZodObject<{
+        verbatim: z.ZodOptional<z.ZodString>;
+        instructions: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     status: z.ZodEnum<{
         error: "error";
         interrupt: "interrupt";
@@ -766,6 +1110,31 @@ type FlowGraph = {
     nodes: FlowGraphNode[];
     edges: FlowGraphEdge[];
 };
+/**
+ * The intro delivered the first time a session touches the flow.
+ *
+ * A bare string is shorthand for `{ verbatim: "…" }`.
+ *
+ * - `verbatim` — reproduced word for word by the assistant. Use it for legal
+ *   notices (GDPR, data controller, retention) that must survive intact.
+ * - `instructions` — guidance the assistant writes its own opening from.
+ *
+ * Set both and the assistant writes the surrounding prose from
+ * `instructions` while keeping the `verbatim` text untouched.
+ */
+type FlowIntro = string | {
+    /** Text the assistant must reproduce word for word. */
+    verbatim?: string;
+    /** How the assistant should write the introduction around it. */
+    instructions?: string;
+};
+/** Normalized intro as it appears in the flow tool response. */
+type FlowIntroPayload = {
+    /** Deliver word for word — no paraphrase, no translation, no reformatting. */
+    verbatim?: string;
+    /** Guidance for the assistant's own wording. */
+    instructions?: string;
+};
 type FlowConfig = {
     /** Unique identifier for the flow (becomes the MCP tool name) */
     id: string;
@@ -773,6 +1142,26 @@ type FlowConfig = {
     title: string;
     /** Description for the AI (explains when to use this flow) */
     description: string;
+    /**
+     * Opening message for the session's first flow response — an introduction,
+     * a GDPR notice, or both. Attached to whichever response the engine returns
+     * first, so it lands even when pre-filled state skips the flow's opening
+     * nodes, and it is never repeated once delivered.
+     *
+     * @example
+     * ```ts
+     * intro: "Acme is the data controller. Your answers are used for this quote only."
+     * ```
+     *
+     * @example
+     * ```ts
+     * intro: {
+     *   verbatim: "Acme is the data controller. Your answers are deleted after 30 days.",
+     *   instructions: "Introduce yourself as Léa from Acme in one short sentence first.",
+     * }
+     * ```
+     */
+    intro?: FlowIntro;
     /**
      * Define the flow's state — each field the flow collects.
      * Keys are the field names used in `interrupt({ field })`,
@@ -860,11 +1249,35 @@ type RegisteredFlow = {
     graph: () => string;
     flowGraph: FlowGraph;
 };
+/**
+ * The engine's own state for a session, persisted in the same record as the
+ * flow's state and kept strictly apart from it.
+ *
+ * Not flow state: nothing here is declared by the author, reaches a node, or
+ * can be written through `stateUpdates`.
+ *
+ * One optional field per engine feature that carries something across calls. A
+ * field is seeded when the session starts and taken off once the engine has
+ * used it, so presence means "still pending" and absence means "done". Seeding,
+ * reading and persisting all go through `internal-state.ts`, which carries
+ * unrecognized fields through untouched: a field a newer version wrote survives
+ * a call served by an older one, and adding a field never strands sessions
+ * across a deploy.
+ */
+type FlowInternalState = {
+    /**
+     * The flow's intro, waiting to ride on the session's first response. Gone
+     * once delivered, so later responses in the same conversation leave it out.
+     */
+    intro?: FlowIntroPayload;
+};
 type FlowTokenContent = {
     step?: string;
     state: Record<string, unknown>;
     field?: string;
     widgetId?: string;
+    /** The engine's own state for this session. Never flow state. */
+    internal?: FlowInternalState;
 };
 type InterruptQuestionData = {
     question: string;
@@ -880,6 +1293,8 @@ type InterruptQuestionData = {
 };
 type FlowInterruptContent = {
     status: "interrupt";
+    /** Opening message for the session's first flow response. */
+    intro?: FlowIntroPayload;
     /** Single-question shorthand */
     question?: string;
     field?: string;
@@ -892,6 +1307,8 @@ type FlowInterruptContent = {
 };
 type FlowWidgetContent = {
     status: "widget";
+    /** Opening message for the session's first flow response. */
+    intro?: FlowIntroPayload;
     /** Display tool to call */
     tool: string;
     /** Data to pass to the display tool */
@@ -911,12 +1328,72 @@ type FlowWidgetContent = {
 };
 type FlowCompleteContent = {
     status: "complete";
+    /** Opening message for the session's first flow response. */
+    intro?: FlowIntroPayload;
 };
 type FlowErrorContent = {
     status: "error";
     error: string;
 };
 
+/**
+ * Widget steps on the WebMCP surface.
+ *
+ * In a chat host a flow's widget step is a two-call dance: the flow answers
+ * `status: "widget"` naming a display tool, the model calls that tool, and the
+ * host renders the `ui://` template it points at. None of that survives the
+ * trip to a browsing agent. There is no widget host in the agent's window, the
+ * display tool is not advertised on this surface, and the round trip would cost
+ * a turn for a render nobody performs.
+ *
+ * So the step is resolved before the agent ever sees it. The server calls the
+ * display tool, finds its view, and hands the page everything it needs to mount
+ * the widget itself. The agent gets prose that never names a display tool. The
+ * visitor gets the calendar on the page they are already looking at.
+ */
+
+type WidgetStep = {
+    /**
+     * The flow's own response, carried whole.
+     *
+     * Typed as the engine's own `FlowWidgetContent` rather than a local shape, so
+     * a field added to a widget step reaches this file as a type change instead
+     * of being silently dropped. That has already happened once: `intro` was
+     * added to the payload and the surface that hand-rolled this parse kept
+     * working only because it spread the rest through.
+     */
+    payload: FlowWidgetContent;
+    tool: string;
+    data: Record<string, unknown>;
+    interactive: boolean;
+};
+/**
+ * A flow's widget step, or `null` for every other tool result.
+ *
+ * Flow tools answer with a single JSON text block, so anything that does not
+ * parse as JSON with `status: "widget"` and a `tool` to call belongs to someone
+ * else and passes through untouched. That includes ordinary tools, which is
+ * most of them.
+ */
+declare function readWidgetStep(result: WebMcpCallResult): WidgetStep | null;
+/** The status a rewritten widget step reports in place of `"widget"`. */
+type WidgetStepStatus = "widget_shown" | "widget_unavailable";
+/**
+ * The step as the agent should read it.
+ *
+ * Built by editing the flow's own payload rather than composing a new object,
+ * so the fields the protocol requires the agent to echo back survive. Dropping
+ * `sessionId` here breaks the flow several turns later, which is the worst kind
+ * of bug to go looking for.
+ *
+ * `tool` and `description` are the two that must not survive. Both name a
+ * display tool the agent cannot call, and leaving either in place is an
+ * instruction to attempt it.
+ */
+declare function rewriteForAgent(step: WidgetStep, rendered: boolean): Record<string, unknown> & {
+    status: WidgetStepStatus;
+};
+
 /**
  * A LangGraph-inspired state graph builder for MCP tools.
  *
@@ -1142,6 +1619,8 @@ interface WaniWaniClient extends TrackingClient {
     readonly _config: InternalConfig;
     /** Knowledge base client for ingestion, search, and source listing */
     readonly kb: KbClient;
+    /** Documents client for reading a file into typed fields */
+    readonly documents: DocumentsClient;
 }
 interface InternalConfig {
     apiUrl: string;
@@ -1240,4 +1719,4 @@ type WithWaniwaniOptions = {
  */
 declare function withWaniwani(server: McpServer, options?: WithWaniwaniOptions): Promise<McpServer>;
 
-export { type AddNodeConfig, type ConditionFn, END, type FlowConfig, type FlowTestResult, type InferFlowState, type InterruptSignal, type KvStore, type KvStoreSetOptions, MemoryKvStore, type NodeContext, type NodeHandler, type RegisteredFlow, type RegisteredTool, SCOPED_CLIENT_KEY, START, type ScopedWaniWaniClient, StateGraph, type TrackingRouteOptions, type TypedInterrupt, type TypedShowWidget, WaniwaniKvStore, type WidgetSignal, type WithWaniwaniOptions, createFlow, createFlowTestHarness, createTrackingRoute, extractScopedClient, redacted, withWaniwani };
+export { type AddNodeConfig, type AttachedDocument, type AttachedFile, type ConditionFn, END, type FlowConfig, type FlowIntro, type FlowIntroPayload, type FlowTestResult, type InferFlowState, type InterruptSignal, type KvStore, type KvStoreSetOptions, MemoryKvStore, type MetaCarrier, type NodeContext, type NodeHandler, type RegisteredFlow, type RegisteredTool, SCOPED_CLIENT_KEY, START, type ScopedWaniWaniClient, StateGraph, type TrackingRouteOptions, type TypedInterrupt, type TypedShowWidget, WaniwaniKvStore, type WebMcpBridge, type WebMcpBridgeOptions, type WebMcpCallResponse, type WebMcpCallResult, type WebMcpContentBlock, type WebMcpListResponse, type WebMcpPageContext, type WebMcpRequest, type WebMcpTool, type WebMcpWidgetPayload, type WidgetSignal, type WidgetStep, type WidgetStepStatus, type WithWaniwaniOptions, autoHeightFromMeta, createFlow, createFlowTestHarness, createTrackingRoute, createWebMcpBridge, extractScopedClient, isDisplayTool, readWidgetStep, redacted, resourceUriFromMeta, rewriteForAgent, supportsWebMcp, viewUriFor, withWaniwani };