@candor-ui/react 1.7.0 → 1.8.0

package/dist/adapters/claude-agent-sdk.d.ts

@@ -144,6 +144,21 @@ export type FromClaudeAgentOptions = {
      * Claude's own citations and web search results are read without it.
      */
     sourcesFrom?: ((tool: string, input: unknown, output: string) => ToolSource[] | undefined) | undefined;
+    /**
+     * The words for lines the adapter adds to the thread itself, as system messages: when the SDK summarised earlier
+     * messages to make room (`compacted`, given how it was started), and when the conversation was cleared (`cleared`).
+     * Defaults are in English; pass your own for other languages.
+     */
+    eventText?: {
+        compacted?: ((trigger: "manual" | "auto") => string) | undefined;
+        cleared?: string | undefined;
+    } | undefined;
+};
+/** A memory the SDK recalled for a reply: the file (or URL) it came from, and whose memory it is. */
+export type ClaudeRecalledMemory = {
+    path: string;
+    scope: "personal" | "team" | "organization";
+    content?: string | undefined;
 };
 export type ClaudeAgentState = {
     messages: Message[];
@@ -156,6 +171,8 @@ export type ClaudeAgentState = {
     notice?: string | undefined;
     /** The permission mode last reported, by the SDK or the app. Absent until one is. */
     permissionMode?: ClaudePermissionMode | undefined;
+    /** Memories the SDK recalled for each reply, by the reply's message id, for a `MemoryUsed` line under it. Only replies that recalled any. */
+    recalled?: Record<string, ClaudeRecalledMemory[]> | undefined;
 };
 /**
  * Turns Claude Agent SDK events into Candor messages, waiting approvals and usage.

package/dist/adapters/claude-agent-sdk.js

@@ -1,4 +1,8 @@
 import { markdownBlocks, plainBlocks } from "../lib/safe-markdown.js";
+const compactedText = (trigger) => trigger === "auto"
+    ? "Earlier messages were summarised to make room. The agent works from that summary now; the messages above are unchanged."
+    : "Earlier messages were summarised, as asked. The agent works from that summary now; the messages above are unchanged.";
+const clearedText = "The conversation was cleared. The agent doesn’t see the messages above.";
 /**
  * Turns Claude Agent SDK events into Candor messages, waiting approvals and usage.
  * Pure, so it can run on every render; useClaudeAgent calls it for you.
@@ -14,11 +18,35 @@ export function fromClaudeAgentEvents(events, options) {
     let lastCost = 0;
     let notice;
     let permissionMode;
-    const current = (id) => (reply ??= { id, parts: [], reasoning: [], tools: new Map(), live: new Map(), sources: new Map(), inputs: new Map() });
+    const recalled = {};
+    // Memories recalled before the reply they're for has started.
+    let recalling = [];
+    const current = (id) => {
+        if (!reply) {
+            reply = { id, parts: [], reasoning: [], tools: new Map(), live: new Map(), sources: new Map(), inputs: new Map(), memories: recalling };
+            recalling = [];
+        }
+        return reply;
+    };
+    // Lines that arrived while a reply was still going: shown after it, so one turn stays one reply.
+    let afterReply = [];
     const close = (last) => {
-        if (reply)
+        if (reply) {
             messages.push(render(reply, { ...options, model, last }));
+            if (reply.memories.length)
+                recalled[reply.id] = reply.memories;
+        }
         reply = null;
+        messages.push(...afterReply);
+        afterReply = [];
+    };
+    // A line the adapter adds between replies: the app's own words, drawn like any system message.
+    const systemLine = (id, text) => {
+        const line = { id, author: { role: "system" }, status: "complete", blocks: plainBlocks(text) };
+        if (reply)
+            afterReply.push(line);
+        else
+            messages.push(line);
     };
     for (const e of events) {
         // Subagents report through their parent's tool call; the main thread is what the person reads.
@@ -90,6 +118,21 @@ export function fromClaudeAgentEvents(events, options) {
                 else if (e.subtype === "api_retry") {
                     notice = `Claude’s API didn’t answer${e.error_status ? ` (${e.error_status})` : ""}; trying again, attempt ${e.attempt} of ${e.max_retries}.`;
                 }
+                else if (e.subtype === "compact_boundary") {
+                    // Without this line the person can't tell the agent no longer has the earlier messages word for word.
+                    const trigger = e.compact_metadata.trigger;
+                    systemLine(`compact-${e.uuid}`, options.eventText?.compacted?.(trigger) ?? compactedText(trigger));
+                }
+                else if (e.subtype === "memory_recall") {
+                    const found = e.memories.map((m) => ({ path: m.path, scope: m.scope, ...(m.content !== undefined && { content: m.content }) }));
+                    if (reply)
+                        reply.memories.push(...found);
+                    else
+                        recalling.push(...found);
+                }
+                break;
+            case "conversation_reset":
+                systemLine(`reset-${e.uuid}`, options.eventText?.cleared ?? clearedText);
                 break;
             case "stream_event": {
                 const r = current(e.uuid);
@@ -170,6 +213,7 @@ export function fromClaudeAgentEvents(events, options) {
         usage,
         notice: options.running ? notice : undefined,
         permissionMode,
+        recalled,
     };
 }
 /** Adds a source once (by key) and returns its id. Markers count up in the order sources first appear. */

package/dist/chat/composer.d.ts

@@ -13,6 +13,7 @@ export declare const composerStrings: {
     hintSend: string;
     hintNewLine: string;
     hintMention: string;
+    hintCommand: string;
     stop: string;
     send: string;
     dropFiles: string;
@@ -42,7 +43,7 @@ export type ComposerState = "ready" | "sending" | "streaming" | {
  * (`{ kind: "held", reason }`) keeps typing open and says why sending waits.
  * `textareaRef` focuses the box from outside, e.g. after a new project starts.
  */
-declare function Composer({ value, onChange, onSubmit, onStop, state, scope, onScopeClick, mentions, commands, references, onReferencesChange, attachments, onAttach, accept, onRemoveAttachment, placeholder: placeholderProp, label: labelProp, tools, textareaRef, sendShape, className, }: {
+declare function Composer({ value, onChange, onSubmit, onStop, state, scope, onScopeClick, mentions, commands, references, onReferencesChange, attachments, onAttach, accept, onRemoveAttachment, placeholder: placeholderProp, label: labelProp, tools, textareaRef, sendShape, hints, className, }: {
     /** The text in the box. */
     value: string;
     /** Called with the new text as the person types. */
@@ -82,6 +83,11 @@ declare function Composer({ value, onChange, onSubmit, onStop, state, scope, onS
     label?: string | undefined;
     /** Your own controls in the toolbar, after the attach button: a dictation button, a model picker. */
     tools?: React.ReactNode | undefined;
+    /**
+     * The keyboard hints shown at wide widths ("↵ send · ⇧↵ new line"), naming @ and / only when `mentions` or
+     * `commands` are given. Defaults to true; false hides them.
+     */
+    hints?: boolean | undefined;
     /** The text box, to focus it or read its selection from outside. */
     textareaRef?: React.Ref<HTMLTextAreaElement> | undefined;
     /** The send button's shape: "square" (the default, rounded corners) or "round". */

package/dist/chat/composer.js

@@ -20,6 +20,7 @@ export const composerStrings = {
     hintSend: "send",
     hintNewLine: "new line",
     hintMention: "mention",
+    hintCommand: "command",
     stop: "Stop",
     send: "Send",
     dropFiles: "Drop files to attach",
@@ -52,7 +53,7 @@ const hasFiles = (e) => Array.from(e.dataTransfer?.types ?? []).includes("Files"
  * (`{ kind: "held", reason }`) keeps typing open and says why sending waits.
  * `textareaRef` focuses the box from outside, e.g. after a new project starts.
  */
-function Composer({ value, onChange, onSubmit, onStop, state = "ready", scope, onScopeClick, mentions = [], commands = [], references = [], onReferencesChange, attachments = [], onAttach, accept, onRemoveAttachment, placeholder: placeholderProp, label: labelProp, tools, textareaRef, sendShape = "square", className, }) {
+function Composer({ value, onChange, onSubmit, onStop, state = "ready", scope, onScopeClick, mentions = [], commands = [], references = [], onReferencesChange, attachments = [], onAttach, accept, onRemoveAttachment, placeholder: placeholderProp, label: labelProp, tools, textareaRef, sendShape = "square", hints = true, className, }) {
     const kindOf = useEntityKinds();
     const t = useStrings("composer", composerStrings);
     const placeholder = placeholderProp ?? t("placeholder");
@@ -216,6 +217,8 @@ function Composer({ value, onChange, onSubmit, onStop, state = "ready", scope, o
                                             if (files.length)
                                                 onAttach(files);
                                             e.target.value = "";
-                                        } }), _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx("button", { type: "button", "aria-label": t("attachFiles"), disabled: Boolean(locked), onClick: () => fileInput.current?.click(), className: "flex size-8 items-center justify-center rounded-lg text-muted-foreground transition-colors duration-150 hover:bg-accent hover:text-foreground disabled:opacity-40", children: _jsx(Paperclip, { className: "size-4" }) }) }), _jsx(TooltipContent, { children: t("attachFiles") })] })] })), tools, scope && (_jsxs("button", { type: "button", onClick: onScopeClick, disabled: !onScopeClick, className: cn("inline-flex min-w-0 items-center gap-1.5 rounded-lg px-2 py-1 text-xs transition-colors duration-150 enabled:hover:bg-accent", production ? "bg-warning-weak text-warning-text enabled:hover:bg-warning-weak" : "text-muted-foreground"), children: [production ? _jsx(TriangleAlert, { "aria-hidden": true, className: "size-3 shrink-0" }) : _jsx("span", { "aria-hidden": true, className: "size-1.5 shrink-0 rounded-full bg-success" }), _jsxs("span", { className: "truncate", children: [scope.environment, " \u00B7 ", production ? t("production") : (scope.detail ?? t("nonProduction"))] })] })), _jsxs("span", { className: "ms-auto hidden text-2xs text-faint-foreground @lg:inline", children: [_jsx("kbd", { className: "font-sans", children: "\u21B5" }), " ", t("hintSend"), " \u00B7 ", _jsx("kbd", { className: "font-sans", children: "\u21E7\u21B5" }), " ", t("hintNewLine"), " \u00B7 ", _jsx("kbd", { className: "font-sans", children: "@" }), " ", t("hintMention")] }), state === "streaming" && onStop ? (_jsx("button", { type: "button", "aria-label": t("stop"), onClick: onStop, className: cn("ms-auto flex size-8 items-center justify-center bg-foreground text-background transition-transform duration-150 active:scale-95 @lg:ms-1", sendShape === "round" ? "rounded-full" : "rounded-lg"), children: _jsx(Square, { className: "size-3 fill-current" }) })) : (_jsx("button", { type: "button", "aria-label": t("send"), onClick: submit, disabled: !canSend, "aria-busy": state === "sending", className: cn("ms-auto flex size-8 items-center justify-center bg-primary text-primary-foreground transition-[background-color,opacity,transform] duration-150 enabled:hover:bg-primary-hover active:scale-95 disabled:opacity-30 @lg:ms-1", sendShape === "round" ? "rounded-full" : "rounded-lg"), children: state === "sending" ? _jsx(LoaderCircle, { className: "size-4 animate-spin" }) : _jsx(ArrowUp, { className: "size-4", strokeWidth: 2.5 }) }))] })] })] }));
+                                        } }), _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx("button", { type: "button", "aria-label": t("attachFiles"), disabled: Boolean(locked), onClick: () => fileInput.current?.click(), className: "flex size-8 items-center justify-center rounded-lg text-muted-foreground transition-colors duration-150 hover:bg-accent hover:text-foreground disabled:opacity-40", children: _jsx(Paperclip, { className: "size-4" }) }) }), _jsx(TooltipContent, { children: t("attachFiles") })] })] })), tools, scope && (_jsxs("button", { type: "button", onClick: onScopeClick, disabled: !onScopeClick, className: cn("inline-flex min-w-0 items-center gap-1.5 rounded-lg px-2 py-1 text-xs transition-colors duration-150 enabled:hover:bg-accent", production ? "bg-warning-weak text-warning-text enabled:hover:bg-warning-weak" : "text-muted-foreground"), children: [production ? _jsx(TriangleAlert, { "aria-hidden": true, className: "size-3 shrink-0" }) : _jsx("span", { "aria-hidden": true, className: "size-1.5 shrink-0 rounded-full bg-success" }), _jsxs("span", { className: "truncate", children: [scope.environment, " \u00B7 ", production ? t("production") : (scope.detail ?? t("nonProduction"))] })] })), hints && (
+                            // Only what this composer can do: @ and / are named only when there's something for them to offer.
+                            _jsxs("span", { className: "ms-auto hidden text-2xs text-faint-foreground @lg:inline", children: [_jsx("kbd", { className: "font-sans", children: "\u21B5" }), " ", t("hintSend"), " \u00B7 ", _jsx("kbd", { className: "font-sans", children: "\u21E7\u21B5" }), " ", t("hintNewLine"), mentions.length > 0 && (_jsxs(_Fragment, { children: [" · ", _jsx("kbd", { className: "font-sans", children: "@" }), " ", t("hintMention")] })), commands.length > 0 && (_jsxs(_Fragment, { children: [" · ", _jsx("kbd", { className: "font-sans", children: "/" }), " ", t("hintCommand")] }))] })), state === "streaming" && onStop ? (_jsx("button", { type: "button", "aria-label": t("stop"), onClick: onStop, className: cn("ms-auto flex size-8 items-center justify-center bg-foreground text-background transition-transform duration-150 active:scale-95", hints && "@lg:ms-1", sendShape === "round" ? "rounded-full" : "rounded-lg"), children: _jsx(Square, { className: "size-3 fill-current" }) })) : (_jsx("button", { type: "button", "aria-label": t("send"), onClick: submit, disabled: !canSend, "aria-busy": state === "sending", className: cn("ms-auto flex size-8 items-center justify-center bg-primary text-primary-foreground transition-[background-color,opacity,transform] duration-150 enabled:hover:bg-primary-hover active:scale-95 disabled:opacity-30", hints && "@lg:ms-1", sendShape === "round" ? "rounded-full" : "rounded-lg"), children: state === "sending" ? _jsx(LoaderCircle, { className: "size-4 animate-spin" }) : _jsx(ArrowUp, { className: "size-4", strokeWidth: 2.5 }) }))] })] })] }));
 }
 export { Composer };

package/dist/index.d.ts

@@ -42,6 +42,7 @@ export * from "./lib/know.js";
 export * from "./lib/render-prop.js";
 export * from "./chat/ai-disclosure.js";
 export * from "./chat/permission-prompt.js";
+export * from "./lib/mcp-input.js";
 export * from "./lib/utils.js";
 export { ToolCall } from "./chat/tool-call.js";
 export type { ToolCall as ToolCallData } from "./lib/chat.js";

package/dist/index.js

@@ -42,6 +42,7 @@ export * from "./lib/know.js";
 export * from "./lib/render-prop.js";
 export * from "./chat/ai-disclosure.js";
 export * from "./chat/permission-prompt.js";
+export * from "./lib/mcp-input.js";
 export * from "./lib/utils.js";
 export { ToolCall } from "./chat/tool-call.js";
 export { Message } from "./chat/message.js";

package/dist/lib/mcp-input.d.ts

@@ -0,0 +1,316 @@
+/**
+ * MCP's "input required" results (spec 2026-07-28, multi round-trip requests) as Candor data: a server's form becomes
+ * questions for ClarifyingQuestions, a plain confirmation or a link to open becomes a two-answer Decision for
+ * ApprovalDecision, and the person's answers become the `inputResponses` the client sends when it retries the call.
+ * Requests it can't show (sampling, roots, anything newer) stay listed as not supported, never dropped.
+ *
+ * Pure functions on plain data, so they run in the browser or on the server, with any MCP client.
+ *
+ * Checked against https://modelcontextprotocol.io/specification/2026-07-28 (basic/patterns/mrtr, client/elicitation
+ * and the schema): `resultType: "input_required"`, `inputRequests` as a map keyed by the server's ids, `requestState`
+ * echoed back unchanged, and the retry's `inputResponses` keyed the same way. Elicitation results are
+ * `{ action: "accept" | "decline" | "cancel", content? }`.
+ */
+/** A form field's schema, as MCP restricts it: a string, number, boolean or enum. Unknown keys pass through. */
+export type McpFieldSchema = {
+    /** "string", "number", "integer", "boolean" or "array" (a multi-select enum). */
+    type?: string | undefined;
+    /** A short name for the field. */
+    title?: string | undefined;
+    /** What the field is for, in a sentence. */
+    description?: string | undefined;
+    /** The server's default. Shown as the server's suggestion; Candor never fills it in for the person. */
+    default?: string | number | boolean | string[] | undefined;
+    /** A single-select enum without titles. */
+    enum?: string[] | undefined;
+    /** Display names for `enum`, in the same order (the legacy form, still sent by older servers). */
+    enumNames?: string[] | undefined;
+    /** A single-select enum with titles. */
+    oneOf?: {
+        const: string;
+        title?: string | undefined;
+    }[] | undefined;
+    /** A multi-select enum's items: `enum` without titles or `anyOf` with them. */
+    items?: {
+        type?: string | undefined;
+        enum?: string[] | undefined;
+        anyOf?: {
+            const: string;
+            title?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+    /** At least this many choices, for a multi-select. */
+    minItems?: number | undefined;
+    /** At most this many choices, for a multi-select. */
+    maxItems?: number | undefined;
+    /** At least this many characters. */
+    minLength?: number | undefined;
+    /** At most this many characters. */
+    maxLength?: number | undefined;
+    /** "email", "uri", "date" or "date-time". */
+    format?: string | undefined;
+    /** The smallest number allowed. */
+    minimum?: number | undefined;
+    /** The largest number allowed. */
+    maximum?: number | undefined;
+};
+/** An `elicitation/create` request in form mode: a message and a flat schema of primitive fields. */
+export type McpElicitFormRequest = {
+    method: "elicitation/create";
+    params: {
+        /** "form", or left out (which means form). */
+        mode?: "form" | undefined;
+        /** Why the server asks, in its own words. */
+        message: string;
+        requestedSchema: {
+            type: "object";
+            properties: Record<string, McpFieldSchema>;
+            required?: string[] | undefined;
+        };
+    };
+};
+/** An `elicitation/create` request in URL mode: a page the person opens outside the client (sign-in, payment). */
+export type McpElicitUrlRequest = {
+    method: "elicitation/create";
+    params: {
+        mode: "url";
+        /** Why the server asks, in its own words. */
+        message: string;
+        /** The page to open, only once the person agrees. */
+        url: string;
+    };
+};
+/**
+ * A result that asks for more input before the call can finish. At least one of `inputRequests` and `requestState`
+ * is present. Values in `inputRequests` are left `unknown`: a server may send kinds this file doesn't know.
+ */
+export type McpInputRequiredResult = {
+    resultType: "input_required";
+    /** The server's requests, keyed by its own ids. */
+    inputRequests?: Record<string, unknown> | undefined;
+    /** Opaque to the client: sent back exactly as received, never read or changed. */
+    requestState?: string | undefined;
+    _meta?: Record<string, unknown> | undefined;
+};
+/** The answer to one elicitation, as MCP takes it back. `content` only when accepted in form mode. */
+export type McpElicitResult = {
+    action: "accept" | "decline" | "cancel";
+    content?: Record<string, string | number | boolean | string[]> | undefined;
+};
+/**
+ * A question in ClarifyingQuestions' shape (`ClarifyingQuestion`), defined here so this free file needs nothing from
+ * a paid one. The question's id is the form field's name.
+ */
+export type McpQuestion = {
+    id: string;
+    kind: "choice";
+    prompt: string;
+    options: {
+        id: string;
+        label: string;
+        detail?: string | undefined;
+    }[];
+    multiple?: boolean | undefined;
+    /** The server's default, marked as a suggestion and never pre-selected. */
+    recommended?: string | undefined;
+    /** A short label shown above the question: the field's title when it also has a description. */
+    tag?: string | undefined;
+    /** Always false: an MCP enum takes only its own values. */
+    other?: boolean | undefined;
+} | {
+    id: string;
+    kind: "text";
+    prompt: string;
+    /** A hint for the expected format, or the server's default, never filled in. */
+    placeholder?: string | undefined;
+    /** The field isn't required: left empty, it isn't sent. */
+    optional?: boolean | undefined;
+    /** A short label shown above the question. */
+    tag?: string | undefined;
+};
+/** A person's answer, in ClarifyingQuestions' shape (`ClarifyingAnswer`). */
+export type McpQuestionAnswer = {
+    questionId: string;
+    choice?: string[] | undefined;
+    text?: string | undefined;
+};
+/**
+ * A two-answer confirmation in ApprovalDecision's shape (`Decision`), defined here so this free file needs nothing
+ * from a paid one. The choices' ids are "accept" and "decline", which is what the retry sends.
+ */
+export type McpDecision = {
+    id: string;
+    question: string;
+    /** What to decide on, as label and value: the page's host and its full address. */
+    facts?: {
+        label: string;
+        value: string;
+    }[] | undefined;
+    /** Accept first, decline second. */
+    choices: {
+        id: "accept" | "decline";
+        label: string;
+        detail?: string | undefined;
+    }[];
+    state: "open";
+};
+/** One of the server's requests, as Candor shows it. `key` is the server's id for it. */
+export type McpInputItem = 
+/**
+ * A form: answer it with ClarifyingQuestions. `fields` and `required` are the server's schema, which
+ * `mcpInputResponses` checks the answers against.
+ */
+{
+    key: string;
+    kind: "questions";
+    message: string;
+    questions: McpQuestion[];
+    fields: Record<string, McpFieldSchema>;
+    required: string[];
+}
+/** A form with no fields: the server asks to go ahead. Answer it with ApprovalDecision. */
+ | {
+    key: string;
+    kind: "confirm";
+    message: string;
+    decision: McpDecision;
+}
+/**
+ * A page to open outside the client. Show the full `url` and its `host` before the person agrees, and open it only
+ * once they accept (`decision`). `warnings` say why the address deserves a second look.
+ */
+ | {
+    key: string;
+    kind: "url";
+    message: string;
+    url: string;
+    host: string;
+    warnings: string[];
+    decision: McpDecision;
+}
+/** A request Candor can't show: its method (when it has one) and why. Show it; don't drop it. */
+ | {
+    key: string;
+    kind: "unsupported";
+    method?: string | undefined;
+    reason: string;
+    request: unknown;
+};
+/** An input-required result, ready to show. */
+export type McpInputView = {
+    /** One per request, in the server's order. */
+    items: McpInputItem[];
+    /** Sent back exactly as received; absent when the server sent none. */
+    requestState?: string | undefined;
+    /** The server's name as your app knows it (passed in), so the person can tell which server asks. */
+    server?: string | undefined;
+    /** The name the server gives itself in the result's `_meta`. Its own claim: show it as such, if at all. */
+    serverClaims?: string | undefined;
+};
+/** A person's reply to one item, by its key. */
+export type McpInputReply = 
+/** A form, answered: the answers from ClarifyingQuestions. */
+{
+    key: string;
+    action: "accept";
+    answers?: McpQuestionAnswer[] | undefined;
+}
+/** Declined outright, or dismissed without a choice. */
+ | {
+    key: string;
+    action: "decline" | "cancel";
+};
+/** Why an answer can't be sent yet. */
+export type McpInputProblem = {
+    /** The item's key. */
+    key: string;
+    /** The field, for a form. */
+    questionId?: string | undefined;
+    /** Which rule it broke. */
+    code: "unanswered" | "required" | "notAnOption" | "notANumber" | "notAnInteger" | "tooSmall" | "tooLarge" | "tooShort" | "tooLong" | "format" | "tooFew" | "tooMany";
+    /** The same in words, from `mcpInputWords`. */
+    message: string;
+};
+/** What a retry sends, or why it can't be sent yet. */
+export type McpInputResponses = {
+    ok: true;
+    /** The retry's `inputResponses`, keyed by the server's ids. */
+    inputResponses: Record<string, unknown>;
+    /** Keys of requests nothing was sent for (not supported and not answered by your app). The server may ask again. */
+    notSent: string[];
+} | {
+    ok: false;
+    problems: McpInputProblem[];
+};
+/** The words this file writes into questions, decisions and problems. Pass your own to `mcpInputView` or `mcpInputResponses`. */
+export declare const mcpInputWords: {
+    yes: string;
+    no: string;
+    /** The extra option on a choice the server doesn't require. */
+    skip: string;
+    defaultHint: string;
+    formatEmail: string;
+    formatUri: string;
+    formatDate: string;
+    formatDateTime: string;
+    confirm: string;
+    openPage: string;
+    decline: string;
+    host: string;
+    address: string;
+    punycode: string;
+    notHttps: string;
+    badUrl: string;
+    unsupportedSampling: string;
+    unsupportedRoots: string;
+    unsupportedMethod: string;
+    unsupportedShape: string;
+    unsupportedField: string;
+    unanswered: string;
+    required: string;
+    notAnOption: string;
+    notANumber: string;
+    notAnInteger: string;
+    tooSmall: string;
+    tooLarge: string;
+    tooShort: string;
+    tooLong: string;
+    format: string;
+    tooFew: string;
+    tooMany: string;
+};
+/** The words, with any you pass in place of the defaults. */
+export type McpInputWords = Partial<typeof mcpInputWords>;
+/**
+ * Whether a tools/call (or prompts/get, resources/read) result asks for more input. A result without `resultType`
+ * comes from an older server and counts as complete, as the spec says.
+ */
+export declare function isMcpInputRequired(result: unknown): result is McpInputRequiredResult;
+/**
+ * An input-required result as items to show: forms as questions, confirmations and links as decisions, and anything
+ * else as a visible "not supported". Undefined when the result doesn't ask for input. `server` is your app's own name
+ * for the server, which the person should see beside every request.
+ */
+export declare function mcpInputView(result: unknown, options?: {
+    server?: string | undefined;
+    words?: McpInputWords | undefined;
+}): McpInputView | undefined;
+/**
+ * The retry's `inputResponses` for the person's replies, checked against each form's schema first (the spec asks
+ * clients to validate). Every form, confirmation and link needs a reply; a form is sent only once every required
+ * field has a valid answer. `own` holds responses your app made itself, for requests Candor doesn't show (a sampling
+ * or roots answer), keyed by the server's ids; anything left is listed in `notSent`.
+ */
+export declare function mcpInputResponses(view: McpInputView, replies: McpInputReply[], options?: {
+    own?: Record<string, unknown> | undefined;
+    words?: McpInputWords | undefined;
+}): McpInputResponses;
+/**
+ * The params for retrying the original request: its own params (name and arguments for tools/call) with
+ * `inputResponses` and the result's `requestState` exactly as received. A `requestState` from an earlier round is
+ * removed when this result has none, as the spec requires. Send it as a new request with a new JSON-RPC id.
+ */
+export declare function mcpRetryParams<P extends Record<string, unknown>>(original: P, view: Pick<McpInputView, "requestState">, inputResponses: Record<string, unknown>): Omit<P, "inputResponses" | "requestState"> & {
+    inputResponses: Record<string, unknown>;
+    requestState?: string | undefined;
+};

package/dist/lib/mcp-input.js

@@ -0,0 +1,369 @@
+/**
+ * MCP's "input required" results (spec 2026-07-28, multi round-trip requests) as Candor data: a server's form becomes
+ * questions for ClarifyingQuestions, a plain confirmation or a link to open becomes a two-answer Decision for
+ * ApprovalDecision, and the person's answers become the `inputResponses` the client sends when it retries the call.
+ * Requests it can't show (sampling, roots, anything newer) stay listed as not supported, never dropped.
+ *
+ * Pure functions on plain data, so they run in the browser or on the server, with any MCP client.
+ *
+ * Checked against https://modelcontextprotocol.io/specification/2026-07-28 (basic/patterns/mrtr, client/elicitation
+ * and the schema): `resultType: "input_required"`, `inputRequests` as a map keyed by the server's ids, `requestState`
+ * echoed back unchanged, and the retry's `inputResponses` keyed the same way. Elicitation results are
+ * `{ action: "accept" | "decline" | "cancel", content? }`.
+ */
+/** The words this file writes into questions, decisions and problems. Pass your own to `mcpInputView` or `mcpInputResponses`. */
+export const mcpInputWords = {
+    yes: "Yes",
+    no: "No",
+    /** The extra option on a choice the server doesn't require. */
+    skip: "Leave unanswered",
+    defaultHint: "Server’s default: {value}",
+    formatEmail: "name@example.com",
+    formatUri: "https://…",
+    formatDate: "YYYY-MM-DD",
+    formatDateTime: "YYYY-MM-DDTHH:MM",
+    confirm: "Go ahead",
+    openPage: "Open the page",
+    decline: "Decline",
+    host: "Opens",
+    address: "Full address",
+    punycode: "The address uses an encoded name (xn--), which can imitate another site.",
+    notHttps: "The page isn’t on https.",
+    badUrl: "The server sent an address that isn’t a valid URL, so it can’t be opened.",
+    unsupportedSampling: "The server asks the client to run a model prompt (sampling), which this app doesn’t do here.",
+    unsupportedRoots: "The server asks for the client’s folders (roots), which this app doesn’t answer here.",
+    unsupportedMethod: "The server asks for something this app can’t show yet: {method}.",
+    unsupportedShape: "The server’s request isn’t in a shape this app recognises.",
+    unsupportedField: "The form has a field this app can’t show: {field}.",
+    unanswered: "Not answered yet.",
+    required: "An answer is needed.",
+    notAnOption: "That isn’t one of the choices.",
+    notANumber: "That isn’t a number.",
+    notAnInteger: "That needs to be a whole number.",
+    tooSmall: "That needs to be at least {min}.",
+    tooLarge: "That needs to be at most {max}.",
+    tooShort: "That needs at least {min} characters.",
+    tooLong: "That allows at most {max} characters.",
+    format: "That doesn’t look like {format}.",
+    tooFew: "Choose at least {min}.",
+    tooMany: "Choose at most {max}.",
+};
+const fill = (s, vars) => s.replace(/\{(\w+)\}/g, (m, k) => (k in vars ? String(vars[k]) : m));
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** The id of "Leave unanswered" on a choice the server doesn't require; no enum value or "true"/"false" can clash with it. */
+const SKIP = "\u0000skip";
+/* ---------------------------------------------------------------- result → view */
+/**
+ * Whether a tools/call (or prompts/get, resources/read) result asks for more input. A result without `resultType`
+ * comes from an older server and counts as complete, as the spec says.
+ */
+export function isMcpInputRequired(result) {
+    return isObject(result) && result.resultType === "input_required";
+}
+/**
+ * An input-required result as items to show: forms as questions, confirmations and links as decisions, and anything
+ * else as a visible "not supported". Undefined when the result doesn't ask for input. `server` is your app's own name
+ * for the server, which the person should see beside every request.
+ */
+export function mcpInputView(result, options = {}) {
+    if (!isMcpInputRequired(result))
+        return undefined;
+    const w = { ...mcpInputWords, ...options.words };
+    const requests = isObject(result.inputRequests) ? result.inputRequests : {};
+    const items = Object.entries(requests).map(([key, request]) => itemOf(key, request, w));
+    const info = isObject(result._meta) ? result._meta["io.modelcontextprotocol/serverInfo"] : undefined;
+    const claims = isObject(info) ? (typeof info.title === "string" && info.title) || (typeof info.name === "string" && info.name) || undefined : undefined;
+    return {
+        items,
+        ...(typeof result.requestState === "string" && { requestState: result.requestState }),
+        ...(options.server && { server: options.server }),
+        ...(claims && { serverClaims: claims }),
+    };
+}
+function itemOf(key, request, w) {
+    const unsupported = (reason, method) => ({ key, kind: "unsupported", ...(method && { method }), reason, request });
+    if (!isObject(request) || typeof request.method !== "string")
+        return unsupported(w.unsupportedShape);
+    const method = request.method;
+    if (method === "sampling/createMessage")
+        return unsupported(w.unsupportedSampling, method);
+    if (method === "roots/list")
+        return unsupported(w.unsupportedRoots, method);
+    if (method !== "elicitation/create")
+        return unsupported(fill(w.unsupportedMethod, { method }), method);
+    const params = request.params;
+    if (!isObject(params) || typeof params.message !== "string")
+        return unsupported(w.unsupportedShape, method);
+    const message = params.message;
+    const mode = params.mode ?? "form";
+    if (mode === "url") {
+        if (typeof params.url !== "string")
+            return unsupported(w.unsupportedShape, method);
+        let parsed;
+        try {
+            parsed = new URL(params.url);
+        }
+        catch {
+            return unsupported(w.badUrl, method);
+        }
+        if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+            return unsupported(w.badUrl, method);
+        const warnings = [];
+        if (parsed.hostname.split(".").some((part) => part.startsWith("xn--")))
+            warnings.push(w.punycode);
+        if (parsed.protocol !== "https:")
+            warnings.push(w.notHttps);
+        return {
+            key,
+            kind: "url",
+            message,
+            url: params.url,
+            host: parsed.host,
+            warnings,
+            decision: {
+                id: key,
+                question: message,
+                facts: [
+                    { label: w.host, value: parsed.host },
+                    { label: w.address, value: params.url },
+                ],
+                choices: [
+                    { id: "accept", label: w.openPage },
+                    { id: "decline", label: w.decline },
+                ],
+                state: "open",
+            },
+        };
+    }
+    if (mode !== "form")
+        return unsupported(fill(w.unsupportedMethod, { method: `${method} (${String(mode)})` }), method);
+    const schema = params.requestedSchema;
+    if (!isObject(schema) || (schema.properties !== undefined && !isObject(schema.properties)))
+        return unsupported(w.unsupportedShape, method);
+    const properties = (schema.properties ?? {});
+    const required = new Set(Array.isArray(schema.required) ? schema.required.filter((r) => typeof r === "string") : []);
+    const names = Object.keys(properties);
+    if (!names.length) {
+        return {
+            key,
+            kind: "confirm",
+            message,
+            decision: {
+                id: key,
+                question: message,
+                choices: [
+                    { id: "accept", label: w.confirm },
+                    { id: "decline", label: w.decline },
+                ],
+                state: "open",
+            },
+        };
+    }
+    const questions = [];
+    for (const name of names) {
+        const q = questionOf(name, properties[name], required.has(name), w);
+        // One field it can't show makes the whole form unsupported: answering only part of it would send a half-truth.
+        if (!q)
+            return unsupported(fill(w.unsupportedField, { field: name }), method);
+        questions.push(q);
+    }
+    return { key, kind: "questions", message, questions, fields: properties, required: [...required] };
+}
+/** A field's options, when it is an enum (single or multiple); undefined otherwise. */
+function optionsOf(s) {
+    const titled = (list) => Array.isArray(list) && list.every((o) => isObject(o) && typeof o.const === "string")
+        ? list.map((o) => ({ id: o.const, label: typeof o.title === "string" && o.title ? o.title : o.const }))
+        : undefined;
+    const plain = (list, names) => Array.isArray(list) && list.every((v) => typeof v === "string")
+        ? list.map((v, i) => ({ id: v, label: Array.isArray(names) && typeof names[i] === "string" && names[i] ? names[i] : v }))
+        : undefined;
+    if (s.type === "array") {
+        const items = isObject(s.items) ? s.items : undefined;
+        const options = items ? (items.anyOf !== undefined ? titled(items.anyOf) : plain(items.enum)) : undefined;
+        return options ? { options, multiple: true } : undefined;
+    }
+    if (s.type === "string" || s.type === undefined) {
+        if (s.oneOf !== undefined) {
+            const options = titled(s.oneOf);
+            return options ? { options, multiple: false } : undefined;
+        }
+        if (s.enum !== undefined) {
+            const options = plain(s.enum, s.enumNames);
+            return options ? { options, multiple: false } : undefined;
+        }
+    }
+    return undefined;
+}
+const formatHint = (format, w) => format === "email" ? w.formatEmail : format === "uri" ? w.formatUri : format === "date" ? w.formatDate : format === "date-time" ? w.formatDateTime : undefined;
+function questionOf(name, raw, required, w) {
+    if (!isObject(raw))
+        return undefined;
+    const s = raw;
+    const title = typeof s.title === "string" && s.title ? s.title : undefined;
+    const description = typeof s.description === "string" && s.description ? s.description : undefined;
+    const prompt = description ?? title ?? name;
+    const tag = description && title ? title : undefined;
+    const head = { id: name, prompt, ...(tag && { tag }) };
+    const enumOf = optionsOf(s);
+    if (enumOf) {
+        const options = !required && !enumOf.multiple ? [...enumOf.options, { id: SKIP, label: w.skip }] : enumOf.options;
+        const recommended = typeof s.default === "string" && enumOf.options.some((o) => o.id === s.default) ? s.default : undefined;
+        return { ...head, kind: "choice", options, multiple: enumOf.multiple, other: false, ...(recommended && { recommended }) };
+    }
+    if (s.type === "boolean") {
+        const options = [
+            { id: "true", label: w.yes },
+            { id: "false", label: w.no },
+            ...(required ? [] : [{ id: SKIP, label: w.skip }]),
+        ];
+        const recommended = typeof s.default === "boolean" ? String(s.default) : undefined;
+        return { ...head, kind: "choice", options, multiple: false, other: false, ...(recommended && { recommended }) };
+    }
+    if (s.type === "string" || s.type === "number" || s.type === "integer") {
+        const hint = s.default !== undefined && s.default !== null && typeof s.default !== "object" ? fill(w.defaultHint, { value: String(s.default) }) : formatHint(s.format, w);
+        return { ...head, kind: "text", ...(hint && { placeholder: hint }), ...(!required && { optional: true }) };
+    }
+    return undefined;
+}
+/* ---------------------------------------------------------------- answers → retry */
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})?$/;
+function formatOk(format, text) {
+    if (format === "email")
+        return EMAIL.test(text);
+    if (format === "date")
+        return DATE.test(text) && !Number.isNaN(Date.parse(text));
+    if (format === "date-time")
+        return DATE_TIME.test(text) && !Number.isNaN(Date.parse(text));
+    if (format === "uri") {
+        try {
+            return Boolean(new URL(text));
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * The retry's `inputResponses` for the person's replies, checked against each form's schema first (the spec asks
+ * clients to validate). Every form, confirmation and link needs a reply; a form is sent only once every required
+ * field has a valid answer. `own` holds responses your app made itself, for requests Candor doesn't show (a sampling
+ * or roots answer), keyed by the server's ids; anything left is listed in `notSent`.
+ */
+export function mcpInputResponses(view, replies, options = {}) {
+    const w = { ...mcpInputWords, ...options.words };
+    const problems = [];
+    // Keys are the server's ids, so the maps have no prototype: "__proto__" or "toString" is just another key.
+    const inputResponses = Object.create(null);
+    const notSent = [];
+    const problem = (key, code, vars = {}, questionId) => problems.push({ key, ...(questionId !== undefined && { questionId }), code, message: fill(w[code], vars) });
+    for (const item of view.items) {
+        if (item.kind === "unsupported") {
+            if (options.own && Object.hasOwn(options.own, item.key))
+                inputResponses[item.key] = options.own[item.key];
+            else
+                notSent.push(item.key);
+            continue;
+        }
+        const reply = replies.find((r) => r.key === item.key);
+        if (!reply) {
+            problem(item.key, "unanswered");
+            continue;
+        }
+        if (reply.action !== "accept") {
+            inputResponses[item.key] = { action: reply.action };
+            continue;
+        }
+        if (item.kind !== "questions") {
+            // A confirmation or a link: accepting sends no content. For a link, open it now; the server finds out on retry.
+            inputResponses[item.key] = { action: "accept" };
+            continue;
+        }
+        const content = Object.create(null);
+        const before = problems.length;
+        for (const q of item.questions) {
+            const s = item.fields[q.id] ?? {};
+            const required = item.required.includes(q.id);
+            const a = reply.answers?.find((x) => x.questionId === q.id);
+            if (q.kind === "choice") {
+                const picked = (a?.choice ?? []).filter((c) => c !== SKIP);
+                if (picked.some((c) => !q.options.some((o) => o.id === c))) {
+                    problem(item.key, "notAnOption", {}, q.id);
+                    continue;
+                }
+                if (q.multiple) {
+                    if (!picked.length && (!required || s.minItems === 0)) {
+                        if (required)
+                            content[q.id] = [];
+                        continue;
+                    }
+                    if (!picked.length && s.minItems === undefined)
+                        problem(item.key, "required", {}, q.id);
+                    else if (typeof s.minItems === "number" && picked.length < s.minItems)
+                        problem(item.key, "tooFew", { min: s.minItems }, q.id);
+                    else if (typeof s.maxItems === "number" && picked.length > s.maxItems)
+                        problem(item.key, "tooMany", { max: s.maxItems }, q.id);
+                    else
+                        content[q.id] = picked;
+                    continue;
+                }
+                const value = picked[0];
+                if (value === undefined) {
+                    if (required)
+                        problem(item.key, "required", {}, q.id);
+                    continue;
+                }
+                content[q.id] = s.type === "boolean" ? value === "true" : value;
+                continue;
+            }
+            const text = a?.text?.trim() ?? "";
+            if (!text) {
+                if (!q.optional)
+                    problem(item.key, "required", {}, q.id);
+                continue;
+            }
+            if (s.type === "number" || s.type === "integer") {
+                const n = Number(text);
+                if (!Number.isFinite(n))
+                    problem(item.key, "notANumber", {}, q.id);
+                else if (s.type === "integer" && !Number.isInteger(n))
+                    problem(item.key, "notAnInteger", {}, q.id);
+                else if (typeof s.minimum === "number" && n < s.minimum)
+                    problem(item.key, "tooSmall", { min: s.minimum }, q.id);
+                else if (typeof s.maximum === "number" && n > s.maximum)
+                    problem(item.key, "tooLarge", { max: s.maximum }, q.id);
+                else
+                    content[q.id] = n;
+                continue;
+            }
+            if (typeof s.minLength === "number" && text.length < s.minLength)
+                problem(item.key, "tooShort", { min: s.minLength }, q.id);
+            else if (typeof s.maxLength === "number" && text.length > s.maxLength)
+                problem(item.key, "tooLong", { max: s.maxLength }, q.id);
+            else if (!formatOk(s.format, text))
+                problem(item.key, "format", { format: formatHint(s.format, w) ?? String(s.format) }, q.id);
+            else
+                content[q.id] = text;
+        }
+        if (problems.length === before)
+            inputResponses[item.key] = { action: "accept", content };
+    }
+    return problems.length ? { ok: false, problems } : { ok: true, inputResponses, notSent };
+}
+/**
+ * The params for retrying the original request: its own params (name and arguments for tools/call) with
+ * `inputResponses` and the result's `requestState` exactly as received. A `requestState` from an earlier round is
+ * removed when this result has none, as the spec requires. Send it as a new request with a new JSON-RPC id.
+ */
+export function mcpRetryParams(original, view, inputResponses) {
+    const rest = { ...original };
+    delete rest.inputResponses;
+    delete rest.requestState;
+    return {
+        ...rest,
+        inputResponses,
+        ...(view.requestState !== undefined && { requestState: view.requestState }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@candor-ui/react",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Candor UI's free tier as an npm package: React components for agents that do real work, on shadcn/ui and Tailwind 4.",
   "license": "MIT",
   "author": "Methodic LLC",