@paymanai/payman-typescript-ask-sdk 4.0.8 → 4.0.10

package/dist/index.d.mts

@@ -72,19 +72,86 @@ type MessageRole = "user" | "assistant" | "system";
 type StreamProgress = "started" | "processing" | "completed" | "error";
 /** Stage values accepted by the k2 playground API. */
 type AgentStage = "DEVELOPMENT" | "QA" | "PROD";
-type UserActionType = "PAYMENT_APPROVAL" | "PAYEE_APPROVAL";
+/**
+ * Which UI a user-action prompt renders. Derived from the event's
+ * `action` (the MCP elicitation kind) with a schema-based fallback.
+ */
+type UserActionKind = "form" | "verification" | "notification";
+/** Lifecycle hint for a prompt (chiefly verification retries/resends). */
+type UserActionSubAction = "NewRequest" | "RequestResent" | "SubmissionInvalid";
+/** Input mode for a verification code. */
+type VerificationType = "NUMERIC_CODE" | "ALPHANUMERIC_CODE";
+/** A single titled option for a `oneOf` single-select field. */
+type JsonSchemaOption = {
+    const: string;
+    title?: string;
+};
+/**
+ * One field in a `requestedSchema.properties` map. This models the
+ * documented flat JSON-Schema subset the server emits today. It is
+ * standard JSON Schema, so unknown keywords are tolerated (ignored)
+ * and an unknown `type` degrades to a text input on the UI side.
+ */
+type JsonSchemaField = {
+    type?: "string" | "number" | "integer" | "boolean" | (string & {});
+    title?: string;
+    description?: string;
+    default?: unknown;
+    oneOf?: JsonSchemaOption[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    [key: string]: unknown;
+};
+/** The restricted JSON Schema describing a form to render. */
+type RequestedSchema = {
+    type?: string;
+    properties?: Record<string, JsonSchemaField>;
+    required?: string[];
+    [key: string]: unknown;
+};
+/**
+ * A user-action prompt the agent raised mid-stream, built from the
+ * top-level fields of a `USER_ACTION_REQUIRED` event.
+ */
 type UserActionRequest = {
     userActionId: string;
-    userActionType?: UserActionType;
-    message: string;
-    requestedSchema: Record<string, unknown>;
+    /** Classified prompt kind (drives which renderer the UI uses). */
+    kind: UserActionKind;
+    /** Raw MCP elicitation `action` string as sent by the server. */
+    rawAction?: string;
+    subAction?: UserActionSubAction | (string & {});
+    verificationType?: VerificationType;
+    expirySeconds?: number;
+    message?: string;
+    requestedSchema?: RequestedSchema;
     metadata?: Record<string, string>;
+    /** Correlation ids used to group/supersede prompts. */
+    toolCallId?: string;
+    executionId?: string;
+    sessionId?: string;
 };
-type UserActionResult = "approved" | "rejected";
+/** Resolution status of a single active prompt. */
+type UserActionStatus = "pending" | "submitting" | "expired" | "stale";
+/** An active prompt slot: the request plus its live resolution status. */
+type ActiveUserAction = UserActionRequest & {
+    status: UserActionStatus;
+};
+/** A one-way notification surfaced to the user (`USER_NOTIFICATION`). */
+type UserNotification = {
+    id: string;
+    message: string;
+};
+/**
+ * Public user-action state exposed by the chat hook. `prompts` is an
+ * ordered, keyed collection (one slot per `toolCallId`, falling back to
+ * `userActionId`) — typically 0–1 entries for serial runs, more when the
+ * engine elicits from parallel tool calls.
+ */
 type UserActionState = {
-    request: UserActionRequest | null;
-    result: UserActionResult | null;
-    clearOtpTrigger: number;
+    prompts: ActiveUserAction[];
+    notifications: UserNotification[];
 };
 type StreamingStep = {
     id: string;
@@ -112,6 +179,7 @@ type ChunkDisplay = {
     similarityScore?: number;
     rrfScore?: number;
 };
+type MessageFeedbackState = "up" | "down";
 type MessageDisplay = {
     id: string;
     sessionId?: string;
@@ -123,6 +191,11 @@ type MessageDisplay = {
     chunks?: ChunkDisplay[];
     tracingData?: unknown;
     executionId?: string;
+    /**
+     * Existing end-user feedback for this assistant response. Hydrated from
+     * execution history so clients can render the selected thumb as active.
+     */
+    feedback?: MessageFeedbackState | null;
     isStreaming?: boolean;
     streamingContent?: string;
     currentWorker?: string;
@@ -131,8 +204,6 @@ type MessageDisplay = {
     steps?: StreamingStep[];
     isCancelled?: boolean;
     currentExecutingStepId?: string;
-    /** Result of user action (OTP approval/rejection) */
-    userActionResult?: UserActionResult;
     /** Current thinking block text (live, resets per block) */
     activeThinkingText?: string;
     /** All thinking accumulated across blocks (for post-stream display) */
@@ -258,10 +329,14 @@ type ChatCallbacks = {
     }) => void;
     /** Called when session ID changes */
     onSessionIdChange?: (sessionId: string) => void;
-    /** Called when a user action (e.g. OTP) is required */
+    /**
+     * Called when the agent raises a user-action prompt
+     * (`USER_ACTION_REQUIRED`). Fires for both new prompts and
+     * supersedes (a retry/resend that replaces an existing slot).
+     */
     onUserActionRequired?: (request: UserActionRequest) => void;
-    /** Called on user action events (SUCCESS, INVALID, EXPIRED, REJECTED, RESENT, FAILED) */
-    onUserActionEvent?: (eventType: string, message: string) => void;
+    /** Called when the agent pushes a one-way notification (`USER_NOTIFICATION`). */
+    onUserNotification?: (notification: UserNotification) => void;
     /**
      * Fires whenever the current streaming "status message" changes —
      * the user-facing label for whatever stage is running right now
@@ -330,10 +405,19 @@ type UseChatV2Return = {
     getMessages: () => MessageDisplay[];
     isWaitingForResponse: boolean;
     sessionId: string | undefined;
+    /** Active user-action prompts + one-way notifications for this chat. */
     userActionState: UserActionState;
-    approveUserAction: (otp: string) => Promise<void>;
-    rejectUserAction: () => Promise<void>;
-    resendOtp: () => Promise<void>;
+    /**
+     * Submit a prompt's form payload. `content` keys should match the
+     * prompt's `requestedSchema.properties` (e.g. `{ otp: "123456" }`).
+     */
+    submitUserAction: (userActionId: string, content: Record<string, unknown>) => Promise<void>;
+    /** Cancel / decline a prompt. */
+    cancelUserAction: (userActionId: string) => Promise<void>;
+    /** Ask the agent to re-send a prompt (e.g. resend a verification code). */
+    resendUserAction: (userActionId: string) => Promise<void>;
+    /** Dismiss a one-way notification from local state. */
+    dismissNotification: (id: string) => void;
 };
 declare function useChatV2(config: ChatConfig, callbacks?: ChatCallbacks): UseChatV2Return;
 
@@ -416,13 +500,20 @@ type StreamEvent = {
      * "Thinking…" panel rather than the chat bubble.
      */
     text?: string;
-    userActionRequest?: {
-        userActionId: string;
-        userActionType?: string;
-        message: string;
-        requestedSchema: Record<string, unknown>;
-        metadata?: Record<string, string>;
-    };
+    /**
+     * User-action / elicitation fields, carried at the TOP LEVEL of a
+     * `USER_ACTION_REQUIRED` event (and `userActionId`/`message` on
+     * `USER_NOTIFICATION`). The MCP `_meta.action` kind is forwarded
+     * here as `action`; `requestedSchema` is standard JSON Schema.
+     */
+    userActionId?: string;
+    action?: string;
+    subAction?: string;
+    verificationType?: string;
+    expirySeconds?: number;
+    requestedSchema?: Record<string, unknown>;
+    metadata?: Record<string, string>;
+    toolCallId?: string;
     [key: string]: unknown;
 };
 type StreamOptions = {
@@ -447,6 +538,12 @@ declare function streamWorkflowEvents(url: string, body: Record<string, unknown>
  */
 declare function buildFormattedThinking(steps: StreamingStep[] | undefined, allThinkingText: string): string;
 
+/**
+ * Classify a `USER_ACTION_REQUIRED` event into a render kind. Primary
+ * discriminator is the MCP elicitation `action`; we fall back to the
+ * schema shape so unknown/legacy `action` tags still route correctly.
+ */
+declare function classifyUserActionKind(action: string | undefined, schema: RequestedSchema | undefined): UserActionKind;
 type V2EventProcessorState = {
     formattedThinkingText: string;
     finalResponse: string;
@@ -456,9 +553,22 @@ type V2EventProcessorState = {
     executionId?: string;
     hasError: boolean;
     errorMessage: string;
-    userActionRequest?: UserActionRequest;
-    userActionPending: boolean;
-    userActionResult?: UserActionResult;
+    /**
+     * Active user-action prompts, an ordered collection keyed by
+     * `toolCallId` (fallback `userActionId`). Usually 0–1 for serial
+     * runs; multiple when parallel tool calls each elicit.
+     */
+    userActions: ActiveUserAction[];
+    /** One-way notifications surfaced this run (`USER_NOTIFICATION`). */
+    notifications: UserNotification[];
+    /**
+     * Transient: the prompt upserted by the most recent
+     * `USER_ACTION_REQUIRED` event, so the stream manager can fire
+     * `onUserActionRequired` for exactly that prompt. Reset each event.
+     */
+    lastUserAction?: UserActionRequest;
+    /** Transient: the notification pushed by the most recent event. */
+    lastNotification?: UserNotification;
     finalData?: unknown;
     steps: StreamingStep[];
     stepCounter: number;
@@ -469,14 +579,75 @@ type V2EventProcessorState = {
 declare function createInitialV2State(): V2EventProcessorState;
 declare function processStreamEventV2(rawEvent: StreamEvent, state: V2EventProcessorState): V2EventProcessorState;
 
+/** The widget kinds the renderer knows how to draw. */
+type FieldWidget = "text" | "integer" | "decimal" | "boolean" | "select";
+/**
+ * Classify a schema field into a widget kind. `oneOf` always wins
+ * (titled single-select), then `type`. Anything unrecognized — or a
+ * missing type — degrades to a plain text input.
+ */
+declare function classifyField(field: JsonSchemaField | undefined): FieldWidget;
+/**
+ * Fields we can't render as a flat primitive (nested objects, arrays,
+ * tuple/composite schemas). The renderer should skip these rather than
+ * attempt a best-effort input. `oneOf` is NOT considered unsupported —
+ * it's our single-select shape.
+ */
+declare function isNestedOrUnsupported(field: JsonSchemaField | undefined): boolean;
+/** Normalize a field's `oneOf` into a clean option list (drops malformed entries). */
+declare function getOptions(field: JsonSchemaField | undefined): JsonSchemaOption[];
+/** Is `key` required per the schema's `required` array? */
+declare function isRequired(schema: RequestedSchema | undefined, key: string): boolean;
+/**
+ * Coerce a raw widget value into the JSON type the schema declares, so
+ * the submitted `content` round-trips cleanly. Empty/blank values become
+ * `undefined` (the field is simply omitted from the payload). The server
+ * is tolerant of strings, but matching types keeps things clean.
+ */
+declare function coerceValue(field: JsonSchemaField | undefined, raw: unknown): unknown;
+/** Pre-fill value for a field's widget, from `default` (typed loosely for inputs). */
+declare function defaultValueFor(field: JsonSchemaField | undefined): unknown;
+/**
+ * Validate a single field's coerced value. Returns an error string or
+ * `null` when valid. Only the documented keywords are enforced; unknown
+ * keywords are ignored.
+ */
+declare function validateField(field: JsonSchemaField | undefined, value: unknown, required: boolean): string | null;
+/** Ordered list of renderable [key, field] pairs (skips unsupported fields). */
+declare function renderableFields(schema: RequestedSchema | undefined): Array<[string, JsonSchemaField]>;
+/**
+ * Validate a full form. `values` is the raw widget-value map (pre-coercion).
+ * Returns a `{ key: error }` map (empty when the form is valid).
+ */
+declare function validateForm(schema: RequestedSchema | undefined, values: Record<string, unknown>): Record<string, string>;
+/**
+ * Build the schema-typed `content` object to POST on submit. Only fields
+ * present in the schema are included; blank/undefined values are omitted.
+ */
+declare function buildContent(schema: RequestedSchema | undefined, values: Record<string, unknown>): Record<string, unknown>;
+
 type UserActionResponse = {
     success: boolean;
     message: string;
 };
 /**
- * Submit a user action (e.g. OTP verification)
+ * Thrown when a resolution endpoint returns `404`
+ * (`user_action_not_found`): the prompt already resolved, expired, or
+ * the id is unknown. Callers should treat the prompt as no longer
+ * actionable — stop any countdown and clear the form — rather than
+ * surfacing this as a hard error.
+ */
+declare class UserActionStaleError extends Error {
+    readonly userActionId: string;
+    constructor(userActionId: string, message?: string);
+}
+/**
+ * Submit a user action. `content` is the schema-typed form payload sent
+ * straight through to the agent (its keys should match the prompt's
+ * `requestedSchema.properties`) — e.g. `{ otp: "123456" }` for a
+ * verification prompt or `{ amount: 50, confirm: true }` for a form.
  */
-declare function submitUserAction(config: ChatConfig, userActionId: string, data?: Record<string, unknown>): Promise<UserActionResponse>;
+declare function submitUserAction(config: ChatConfig, userActionId: string, content?: Record<string, unknown>): Promise<UserActionResponse>;
 /**
  * Cancel / reject a user action
  */
@@ -486,4 +657,6 @@ declare function cancelUserAction(config: ChatConfig, userActionId: string): Pro
  */
 declare function resendUserAction(config: ChatConfig, userActionId: string): Promise<UserActionResponse>;
 
-export { type APIConfig, type AgentStage, type AnalysisMode, type ChatCallbacks, type ChatConfig, type ChunkDisplay, type MessageDisplay, type MessageRole, type SendMessageOptions, type SessionParams, type StreamEvent, type StreamOptions, type StreamProgress, type StreamingStep, type UseChatV2Return, type UseVoiceReturn, type UserActionRequest, type UserActionResult, type UserActionState, type UserActionType, type V2EventProcessorState, type VoiceCallbacks, type VoiceConfig, type VoicePermissions, type VoiceResult, type VoiceState, buildFormattedThinking, cancelUserAction, createInitialV2State, generateId, processStreamEventV2, resendUserAction, streamWorkflowEvents, submitUserAction, useChatV2, useVoice };
+declare function migrateActiveStream(oldUserId: string, newUserId: string): void;
+
+export { type APIConfig, type ActiveUserAction, type AgentStage, type AnalysisMode, type ChatCallbacks, type ChatConfig, type ChunkDisplay, type FieldWidget, type JsonSchemaField, type JsonSchemaOption, type MessageDisplay, type MessageFeedbackState, type MessageRole, type RequestedSchema, type SendMessageOptions, type SessionParams, type StreamEvent, type StreamOptions, type StreamProgress, type StreamingStep, type UseChatV2Return, type UseVoiceReturn, type UserActionKind, type UserActionRequest, UserActionStaleError, type UserActionState, type UserActionStatus, type UserActionSubAction, type UserNotification, type V2EventProcessorState, type VerificationType, type VoiceCallbacks, type VoiceConfig, type VoicePermissions, type VoiceResult, type VoiceState, buildContent, buildFormattedThinking, cancelUserAction, classifyField, classifyUserActionKind, coerceValue, createInitialV2State, defaultValueFor, generateId, getOptions, isNestedOrUnsupported, isRequired, migrateActiveStream, processStreamEventV2, renderableFields, resendUserAction, streamWorkflowEvents, submitUserAction, useChatV2, useVoice, validateField, validateForm };

package/dist/index.d.ts

@@ -72,19 +72,86 @@ type MessageRole = "user" | "assistant" | "system";
 type StreamProgress = "started" | "processing" | "completed" | "error";
 /** Stage values accepted by the k2 playground API. */
 type AgentStage = "DEVELOPMENT" | "QA" | "PROD";
-type UserActionType = "PAYMENT_APPROVAL" | "PAYEE_APPROVAL";
+/**
+ * Which UI a user-action prompt renders. Derived from the event's
+ * `action` (the MCP elicitation kind) with a schema-based fallback.
+ */
+type UserActionKind = "form" | "verification" | "notification";
+/** Lifecycle hint for a prompt (chiefly verification retries/resends). */
+type UserActionSubAction = "NewRequest" | "RequestResent" | "SubmissionInvalid";
+/** Input mode for a verification code. */
+type VerificationType = "NUMERIC_CODE" | "ALPHANUMERIC_CODE";
+/** A single titled option for a `oneOf` single-select field. */
+type JsonSchemaOption = {
+    const: string;
+    title?: string;
+};
+/**
+ * One field in a `requestedSchema.properties` map. This models the
+ * documented flat JSON-Schema subset the server emits today. It is
+ * standard JSON Schema, so unknown keywords are tolerated (ignored)
+ * and an unknown `type` degrades to a text input on the UI side.
+ */
+type JsonSchemaField = {
+    type?: "string" | "number" | "integer" | "boolean" | (string & {});
+    title?: string;
+    description?: string;
+    default?: unknown;
+    oneOf?: JsonSchemaOption[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    [key: string]: unknown;
+};
+/** The restricted JSON Schema describing a form to render. */
+type RequestedSchema = {
+    type?: string;
+    properties?: Record<string, JsonSchemaField>;
+    required?: string[];
+    [key: string]: unknown;
+};
+/**
+ * A user-action prompt the agent raised mid-stream, built from the
+ * top-level fields of a `USER_ACTION_REQUIRED` event.
+ */
 type UserActionRequest = {
     userActionId: string;
-    userActionType?: UserActionType;
-    message: string;
-    requestedSchema: Record<string, unknown>;
+    /** Classified prompt kind (drives which renderer the UI uses). */
+    kind: UserActionKind;
+    /** Raw MCP elicitation `action` string as sent by the server. */
+    rawAction?: string;
+    subAction?: UserActionSubAction | (string & {});
+    verificationType?: VerificationType;
+    expirySeconds?: number;
+    message?: string;
+    requestedSchema?: RequestedSchema;
     metadata?: Record<string, string>;
+    /** Correlation ids used to group/supersede prompts. */
+    toolCallId?: string;
+    executionId?: string;
+    sessionId?: string;
 };
-type UserActionResult = "approved" | "rejected";
+/** Resolution status of a single active prompt. */
+type UserActionStatus = "pending" | "submitting" | "expired" | "stale";
+/** An active prompt slot: the request plus its live resolution status. */
+type ActiveUserAction = UserActionRequest & {
+    status: UserActionStatus;
+};
+/** A one-way notification surfaced to the user (`USER_NOTIFICATION`). */
+type UserNotification = {
+    id: string;
+    message: string;
+};
+/**
+ * Public user-action state exposed by the chat hook. `prompts` is an
+ * ordered, keyed collection (one slot per `toolCallId`, falling back to
+ * `userActionId`) — typically 0–1 entries for serial runs, more when the
+ * engine elicits from parallel tool calls.
+ */
 type UserActionState = {
-    request: UserActionRequest | null;
-    result: UserActionResult | null;
-    clearOtpTrigger: number;
+    prompts: ActiveUserAction[];
+    notifications: UserNotification[];
 };
 type StreamingStep = {
     id: string;
@@ -112,6 +179,7 @@ type ChunkDisplay = {
     similarityScore?: number;
     rrfScore?: number;
 };
+type MessageFeedbackState = "up" | "down";
 type MessageDisplay = {
     id: string;
     sessionId?: string;
@@ -123,6 +191,11 @@ type MessageDisplay = {
     chunks?: ChunkDisplay[];
     tracingData?: unknown;
     executionId?: string;
+    /**
+     * Existing end-user feedback for this assistant response. Hydrated from
+     * execution history so clients can render the selected thumb as active.
+     */
+    feedback?: MessageFeedbackState | null;
     isStreaming?: boolean;
     streamingContent?: string;
     currentWorker?: string;
@@ -131,8 +204,6 @@ type MessageDisplay = {
     steps?: StreamingStep[];
     isCancelled?: boolean;
     currentExecutingStepId?: string;
-    /** Result of user action (OTP approval/rejection) */
-    userActionResult?: UserActionResult;
     /** Current thinking block text (live, resets per block) */
     activeThinkingText?: string;
     /** All thinking accumulated across blocks (for post-stream display) */
@@ -258,10 +329,14 @@ type ChatCallbacks = {
     }) => void;
     /** Called when session ID changes */
     onSessionIdChange?: (sessionId: string) => void;
-    /** Called when a user action (e.g. OTP) is required */
+    /**
+     * Called when the agent raises a user-action prompt
+     * (`USER_ACTION_REQUIRED`). Fires for both new prompts and
+     * supersedes (a retry/resend that replaces an existing slot).
+     */
     onUserActionRequired?: (request: UserActionRequest) => void;
-    /** Called on user action events (SUCCESS, INVALID, EXPIRED, REJECTED, RESENT, FAILED) */
-    onUserActionEvent?: (eventType: string, message: string) => void;
+    /** Called when the agent pushes a one-way notification (`USER_NOTIFICATION`). */
+    onUserNotification?: (notification: UserNotification) => void;
     /**
      * Fires whenever the current streaming "status message" changes —
      * the user-facing label for whatever stage is running right now
@@ -330,10 +405,19 @@ type UseChatV2Return = {
     getMessages: () => MessageDisplay[];
     isWaitingForResponse: boolean;
     sessionId: string | undefined;
+    /** Active user-action prompts + one-way notifications for this chat. */
     userActionState: UserActionState;
-    approveUserAction: (otp: string) => Promise<void>;
-    rejectUserAction: () => Promise<void>;
-    resendOtp: () => Promise<void>;
+    /**
+     * Submit a prompt's form payload. `content` keys should match the
+     * prompt's `requestedSchema.properties` (e.g. `{ otp: "123456" }`).
+     */
+    submitUserAction: (userActionId: string, content: Record<string, unknown>) => Promise<void>;
+    /** Cancel / decline a prompt. */
+    cancelUserAction: (userActionId: string) => Promise<void>;
+    /** Ask the agent to re-send a prompt (e.g. resend a verification code). */
+    resendUserAction: (userActionId: string) => Promise<void>;
+    /** Dismiss a one-way notification from local state. */
+    dismissNotification: (id: string) => void;
 };
 declare function useChatV2(config: ChatConfig, callbacks?: ChatCallbacks): UseChatV2Return;
 
@@ -416,13 +500,20 @@ type StreamEvent = {
      * "Thinking…" panel rather than the chat bubble.
      */
     text?: string;
-    userActionRequest?: {
-        userActionId: string;
-        userActionType?: string;
-        message: string;
-        requestedSchema: Record<string, unknown>;
-        metadata?: Record<string, string>;
-    };
+    /**
+     * User-action / elicitation fields, carried at the TOP LEVEL of a
+     * `USER_ACTION_REQUIRED` event (and `userActionId`/`message` on
+     * `USER_NOTIFICATION`). The MCP `_meta.action` kind is forwarded
+     * here as `action`; `requestedSchema` is standard JSON Schema.
+     */
+    userActionId?: string;
+    action?: string;
+    subAction?: string;
+    verificationType?: string;
+    expirySeconds?: number;
+    requestedSchema?: Record<string, unknown>;
+    metadata?: Record<string, string>;
+    toolCallId?: string;
     [key: string]: unknown;
 };
 type StreamOptions = {
@@ -447,6 +538,12 @@ declare function streamWorkflowEvents(url: string, body: Record<string, unknown>
  */
 declare function buildFormattedThinking(steps: StreamingStep[] | undefined, allThinkingText: string): string;
 
+/**
+ * Classify a `USER_ACTION_REQUIRED` event into a render kind. Primary
+ * discriminator is the MCP elicitation `action`; we fall back to the
+ * schema shape so unknown/legacy `action` tags still route correctly.
+ */
+declare function classifyUserActionKind(action: string | undefined, schema: RequestedSchema | undefined): UserActionKind;
 type V2EventProcessorState = {
     formattedThinkingText: string;
     finalResponse: string;
@@ -456,9 +553,22 @@ type V2EventProcessorState = {
     executionId?: string;
     hasError: boolean;
     errorMessage: string;
-    userActionRequest?: UserActionRequest;
-    userActionPending: boolean;
-    userActionResult?: UserActionResult;
+    /**
+     * Active user-action prompts, an ordered collection keyed by
+     * `toolCallId` (fallback `userActionId`). Usually 0–1 for serial
+     * runs; multiple when parallel tool calls each elicit.
+     */
+    userActions: ActiveUserAction[];
+    /** One-way notifications surfaced this run (`USER_NOTIFICATION`). */
+    notifications: UserNotification[];
+    /**
+     * Transient: the prompt upserted by the most recent
+     * `USER_ACTION_REQUIRED` event, so the stream manager can fire
+     * `onUserActionRequired` for exactly that prompt. Reset each event.
+     */
+    lastUserAction?: UserActionRequest;
+    /** Transient: the notification pushed by the most recent event. */
+    lastNotification?: UserNotification;
     finalData?: unknown;
     steps: StreamingStep[];
     stepCounter: number;
@@ -469,14 +579,75 @@ type V2EventProcessorState = {
 declare function createInitialV2State(): V2EventProcessorState;
 declare function processStreamEventV2(rawEvent: StreamEvent, state: V2EventProcessorState): V2EventProcessorState;
 
+/** The widget kinds the renderer knows how to draw. */
+type FieldWidget = "text" | "integer" | "decimal" | "boolean" | "select";
+/**
+ * Classify a schema field into a widget kind. `oneOf` always wins
+ * (titled single-select), then `type`. Anything unrecognized — or a
+ * missing type — degrades to a plain text input.
+ */
+declare function classifyField(field: JsonSchemaField | undefined): FieldWidget;
+/**
+ * Fields we can't render as a flat primitive (nested objects, arrays,
+ * tuple/composite schemas). The renderer should skip these rather than
+ * attempt a best-effort input. `oneOf` is NOT considered unsupported —
+ * it's our single-select shape.
+ */
+declare function isNestedOrUnsupported(field: JsonSchemaField | undefined): boolean;
+/** Normalize a field's `oneOf` into a clean option list (drops malformed entries). */
+declare function getOptions(field: JsonSchemaField | undefined): JsonSchemaOption[];
+/** Is `key` required per the schema's `required` array? */
+declare function isRequired(schema: RequestedSchema | undefined, key: string): boolean;
+/**
+ * Coerce a raw widget value into the JSON type the schema declares, so
+ * the submitted `content` round-trips cleanly. Empty/blank values become
+ * `undefined` (the field is simply omitted from the payload). The server
+ * is tolerant of strings, but matching types keeps things clean.
+ */
+declare function coerceValue(field: JsonSchemaField | undefined, raw: unknown): unknown;
+/** Pre-fill value for a field's widget, from `default` (typed loosely for inputs). */
+declare function defaultValueFor(field: JsonSchemaField | undefined): unknown;
+/**
+ * Validate a single field's coerced value. Returns an error string or
+ * `null` when valid. Only the documented keywords are enforced; unknown
+ * keywords are ignored.
+ */
+declare function validateField(field: JsonSchemaField | undefined, value: unknown, required: boolean): string | null;
+/** Ordered list of renderable [key, field] pairs (skips unsupported fields). */
+declare function renderableFields(schema: RequestedSchema | undefined): Array<[string, JsonSchemaField]>;
+/**
+ * Validate a full form. `values` is the raw widget-value map (pre-coercion).
+ * Returns a `{ key: error }` map (empty when the form is valid).
+ */
+declare function validateForm(schema: RequestedSchema | undefined, values: Record<string, unknown>): Record<string, string>;
+/**
+ * Build the schema-typed `content` object to POST on submit. Only fields
+ * present in the schema are included; blank/undefined values are omitted.
+ */
+declare function buildContent(schema: RequestedSchema | undefined, values: Record<string, unknown>): Record<string, unknown>;
+
 type UserActionResponse = {
     success: boolean;
     message: string;
 };
 /**
- * Submit a user action (e.g. OTP verification)
+ * Thrown when a resolution endpoint returns `404`
+ * (`user_action_not_found`): the prompt already resolved, expired, or
+ * the id is unknown. Callers should treat the prompt as no longer
+ * actionable — stop any countdown and clear the form — rather than
+ * surfacing this as a hard error.
+ */
+declare class UserActionStaleError extends Error {
+    readonly userActionId: string;
+    constructor(userActionId: string, message?: string);
+}
+/**
+ * Submit a user action. `content` is the schema-typed form payload sent
+ * straight through to the agent (its keys should match the prompt's
+ * `requestedSchema.properties`) — e.g. `{ otp: "123456" }` for a
+ * verification prompt or `{ amount: 50, confirm: true }` for a form.
  */
-declare function submitUserAction(config: ChatConfig, userActionId: string, data?: Record<string, unknown>): Promise<UserActionResponse>;
+declare function submitUserAction(config: ChatConfig, userActionId: string, content?: Record<string, unknown>): Promise<UserActionResponse>;
 /**
  * Cancel / reject a user action
  */
@@ -486,4 +657,6 @@ declare function cancelUserAction(config: ChatConfig, userActionId: string): Pro
  */
 declare function resendUserAction(config: ChatConfig, userActionId: string): Promise<UserActionResponse>;
 
-export { type APIConfig, type AgentStage, type AnalysisMode, type ChatCallbacks, type ChatConfig, type ChunkDisplay, type MessageDisplay, type MessageRole, type SendMessageOptions, type SessionParams, type StreamEvent, type StreamOptions, type StreamProgress, type StreamingStep, type UseChatV2Return, type UseVoiceReturn, type UserActionRequest, type UserActionResult, type UserActionState, type UserActionType, type V2EventProcessorState, type VoiceCallbacks, type VoiceConfig, type VoicePermissions, type VoiceResult, type VoiceState, buildFormattedThinking, cancelUserAction, createInitialV2State, generateId, processStreamEventV2, resendUserAction, streamWorkflowEvents, submitUserAction, useChatV2, useVoice };
+declare function migrateActiveStream(oldUserId: string, newUserId: string): void;
+
+export { type APIConfig, type ActiveUserAction, type AgentStage, type AnalysisMode, type ChatCallbacks, type ChatConfig, type ChunkDisplay, type FieldWidget, type JsonSchemaField, type JsonSchemaOption, type MessageDisplay, type MessageFeedbackState, type MessageRole, type RequestedSchema, type SendMessageOptions, type SessionParams, type StreamEvent, type StreamOptions, type StreamProgress, type StreamingStep, type UseChatV2Return, type UseVoiceReturn, type UserActionKind, type UserActionRequest, UserActionStaleError, type UserActionState, type UserActionStatus, type UserActionSubAction, type UserNotification, type V2EventProcessorState, type VerificationType, type VoiceCallbacks, type VoiceConfig, type VoicePermissions, type VoiceResult, type VoiceState, buildContent, buildFormattedThinking, cancelUserAction, classifyField, classifyUserActionKind, coerceValue, createInitialV2State, defaultValueFor, generateId, getOptions, isNestedOrUnsupported, isRequired, migrateActiveStream, processStreamEventV2, renderableFields, resendUserAction, streamWorkflowEvents, submitUserAction, useChatV2, useVoice, validateField, validateForm };