@xinghunm/ai-chat 0.4.0 → 1.0.1

package/dist/index.d.mts

@@ -101,6 +101,7 @@ interface PlanBooleanQuestion extends PlanQuestionBase {
  * Supported question variants in a plan questionnaire.
  */
 type PlanQuestion = PlanSingleSelectQuestion | PlanMultiSelectQuestion | PlanTextQuestion | PlanNumberQuestion | PlanBooleanQuestion;
+type PlanQuestionnaireStatus = 'expired' | 'failed';
 /**
  * Structured question form emitted for plan-mode clarification flows.
  */
@@ -111,6 +112,8 @@ interface PlanQuestionnaire {
     submitLabel?: string;
     questions: PlanQuestion[];
     answers?: Partial<Record<string, PlanQuestionnaireAnswerValue>>;
+    status?: PlanQuestionnaireStatus;
+    statusMessage?: string;
 }
 /**
  * Submission payload emitted by a questionnaire card.
@@ -129,6 +132,13 @@ interface ExecutionConfirmationSubmission {
     content: string;
     sourceMessageId?: string;
 }
+/**
+ * Context metadata provided to custom structured submission handlers.
+ */
+interface ChatSubmissionContext {
+    sessionId?: string;
+    mode: ChatAgentMode;
+}
 /**
  * Summary item used by structured assistant cards to describe parameter changes.
  */
@@ -142,22 +152,47 @@ interface ChatParameterSummaryItem {
  */
 interface ExecutionProposal {
     proposalId: string;
-    equationKey: string;
-    equationName: string;
-    solverName?: string;
+    resourceKey: string;
+    resourceName: string;
+    executorName?: string;
     parameterSummary: ChatParameterSummaryItem[];
     warnings?: string[];
     requiresConfirmation: true;
 }
 /**
- * Structured result summary emitted after a PDE task has started or completed.
+ * Structured result summary emitted after a task has started or completed.
  */
 interface ResultSummary {
-    taskId: string;
+    summaryId: string;
     status: 'completed' | 'failed' | 'running' | 'pending';
     headline: string;
     details: string[];
 }
+/**
+ * Merge behavior applied when a keyed custom block is patched repeatedly.
+ */
+type ChatCustomBlockMergePolicy = 'append' | 'replace' | 'ignore-duplicate';
+/**
+ * Extensible custom block rendered by a consumer-provided block renderer.
+ */
+interface ChatCustomBlock {
+    type: 'custom';
+    kind: string;
+    data: unknown;
+    /**
+     * Stable key used to identify the same logical block across streaming patches.
+     * When present, keyed custom blocks are merged by `blockKey` regardless of `kind`.
+     */
+    blockKey?: string;
+    /**
+     * Merge strategy used when another custom block with the same key arrives.
+     *
+     * - `append`: keep appending blocks even if the key matches.
+     * - `replace`: replace the existing keyed block with the latest one.
+     * - `ignore-duplicate`: keep the first keyed block and ignore later duplicates.
+     */
+    mergePolicy?: ChatCustomBlockMergePolicy;
+}
 /**
  * Structured assistant block variants rendered by the chat thread.
  */
@@ -180,11 +215,7 @@ type ChatMessageBlock = {
 } | {
     type: 'questionnaire';
     questionnaire: PlanQuestionnaire;
-} | {
-    type: 'custom';
-    kind: string;
-    data: unknown;
-};
+} | ChatCustomBlock;
 /**
  * Supported message body render orders for mixed text and structured blocks.
  */
@@ -279,6 +310,14 @@ interface ChatMessageBlockRendererProps {
  * Optional renderer used for custom block variants.
  */
 type ChatMessageBlockRenderer = (props: ChatMessageBlockRendererProps) => ReactNode;
+/**
+ * Optional application-provided handler that intercepts questionnaire submissions.
+ */
+type ChatQuestionnaireSubmitHandler = (submission: PlanQuestionnaireSubmission, context: ChatSubmissionContext) => Promise<boolean | void> | boolean | void;
+/**
+ * Optional application-provided handler that intercepts confirmation submissions.
+ */
+type ChatConfirmationSubmitHandler = (submission: ExecutionConfirmationSubmission, context: ChatSubmissionContext) => Promise<boolean | void> | boolean | void;
 interface ChatModel {
     id: string;
     object: string;
@@ -336,10 +375,18 @@ interface AiChatLabels {
     attachmentLimitNotice?: string;
     userRoleLabel?: string;
     assistantRoleLabel?: string;
+    expandMessageAriaLabel?: string;
+    collapseMessageAriaLabel?: string;
+    expandComposerAriaLabel?: string;
+    collapseComposerAriaLabel?: string;
     stoppedResponse?: string;
     assistantStreamingAriaLabel?: string;
     networkError?: string;
     genericError?: string;
+    questionnaireSubmitting?: string;
+    questionnaireSubmitted?: string;
+    questionnaireValidationPrefix?: string;
+    questionnaireSubmitFailed?: string;
 }
 /**
  * Default English label values used when no labels are provided.
@@ -353,6 +400,10 @@ interface AiChatProviderBaseProps {
     labels?: AiChatLabels;
     /** Optional renderer used to extend message blocks with app-specific UI. */
     renderMessageBlock?: ChatMessageBlockRenderer;
+    /** Optional handler used to intercept questionnaire submissions before the default send flow. */
+    handleQuestionnaireSubmit?: ChatQuestionnaireSubmitHandler;
+    /** Optional handler used to intercept confirmation submissions before the default send flow. */
+    handleConfirmationSubmit?: ChatConfirmationSubmitHandler;
     /** Optional render order used for mixed text and structured message blocks. */
     messageRenderOrder?: ChatMessageRenderOrder;
     /**
@@ -416,6 +467,17 @@ interface DefaultChatTransportEndpoints {
     /** Relative path used to request stream termination. */
     terminate?: string;
 }
+/**
+ * Tool execution policy applied to outgoing stream requests.
+ */
+interface ChatToolExecutionPolicy {
+    /** Enables tool execution headers for the stream request. */
+    enabled?: boolean;
+    /** Marks the request as requiring explicit approval before tool execution. */
+    approvalRequired?: boolean;
+    /** Approval timeout in seconds, forwarded when approval is enabled. */
+    approvalTimeoutSec?: number;
+}
 /**
  * Options for the built-in HTTP transport adapter.
  */
@@ -424,6 +486,8 @@ interface CreateDefaultChatTransportOptions {
     apiBaseUrl: string;
     /** Authorization header value forwarded to the backend. */
     authToken: string;
+    /** Optional tool execution policy translated into stream request headers. */
+    toolExecutionPolicy?: ChatToolExecutionPolicy;
     /** Optional extra headers appended to each streaming chat completion request. */
     streamHeaders?: Record<string, string>;
     /** Optional transformer used to normalize custom stream packets. */
@@ -436,7 +500,7 @@ interface CreateDefaultChatTransportOptions {
 /**
  * Creates the built-in transport backed by the current HTTP chat API.
  */
-declare const createDefaultChatTransport: ({ apiBaseUrl, authToken, streamHeaders, transformStreamPacket, endpoints, axiosInstance, }: CreateDefaultChatTransportOptions) => ChatTransport;
+declare const createDefaultChatTransport: ({ apiBaseUrl, authToken, toolExecutionPolicy, streamHeaders, transformStreamPacket, endpoints, axiosInstance, }: CreateDefaultChatTransportOptions) => ChatTransport;
 
 declare const ChatThread: () => _emotion_react_jsx_runtime.JSX.Element;
 
@@ -466,6 +530,8 @@ interface ChatComposerViewProps {
         plan: string;
         agent: string;
     };
+    expandComposerAriaLabel: string;
+    collapseComposerAriaLabel: string;
     onValueChange: (value: string) => void;
     onPickImages: (files: FileList | File[]) => void;
     onPasteImages: (files: File[]) => void;
@@ -529,6 +595,10 @@ interface ChatContextValue {
     retryRef: MutableRefObject<() => Promise<void>>;
     /** Optional block renderer used to extend message rendering with custom block types. */
     renderMessageBlock?: ChatMessageBlockRenderer;
+    /** Optional handler used to intercept questionnaire submissions before the default send flow. */
+    handleQuestionnaireSubmit?: ChatQuestionnaireSubmitHandler;
+    /** Optional handler used to intercept confirmation submissions before the default send flow. */
+    handleConfirmationSubmit?: ChatConfirmationSubmitHandler;
     /** Optional render order used for mixed text and structured message blocks. */
     messageRenderOrder?: ChatMessageRenderOrder;
     /** Optional packet transformer used by the legacy default adapter. */
@@ -551,4 +621,4 @@ declare const useChatContext: () => ChatContextValue;
  */
 declare const useChatStore: <T>(selector: (state: ChatStore) => T) => T;
 
-export { AiChat, type AiChatLabels, type AiChatProps, AiChatProvider, type AiChatProviderProps, CHAT_AGENT_MODES, CHAT_MESSAGE_RENDER_ORDERS, type ChatAgentMode, ChatComposer, type ChatComposerViewProps, ChatConversationList, type ChatImageAttachment, type ChatMessage, type ChatMessageBlock, type ChatMessageBlockRenderer, type ChatMessageBlockRendererProps, type ChatMessageRenderOrder, type ChatMessageStatus, type ChatModel, type ChatRole, type ChatSession, type ChatStreamMessagePatch, type ChatStreamPacketTransformArgs, type ChatStreamPacketUpdate, ChatThread, type ChatTransport, type ChatTransportStartStreamArgs, type CreateDefaultChatTransportOptions, DEFAULT_AI_CHAT_LABELS, DEFAULT_CHAT_AGENT_MODE, type DefaultChatTransportEndpoints, type ExecutionConfirmationSubmission, type ExecutionProposal, type PlanQuestionnaire, type PlanQuestionnaireSubmission, type ResultSummary, type TransformChatStreamPacket, createDefaultChatTransport, useChatContext, useChatStore };
+export { AiChat, type AiChatLabels, type AiChatProps, AiChatProvider, type AiChatProviderProps, CHAT_AGENT_MODES, CHAT_MESSAGE_RENDER_ORDERS, type ChatAgentMode, ChatComposer, type ChatComposerViewProps, type ChatConfirmationSubmitHandler, ChatConversationList, type ChatImageAttachment, type ChatMessage, type ChatMessageBlock, type ChatMessageBlockRenderer, type ChatMessageBlockRendererProps, type ChatMessageRenderOrder, type ChatMessageStatus, type ChatModel, type ChatParameterSummaryItem, type ChatQuestionnaireSubmitHandler, type ChatRole, type ChatSession, type ChatStreamMessagePatch, type ChatStreamPacketTransformArgs, type ChatStreamPacketUpdate, type ChatSubmissionContext, ChatThread, type ChatToolExecutionPolicy, type ChatTransport, type ChatTransportStartStreamArgs, type CreateDefaultChatTransportOptions, DEFAULT_AI_CHAT_LABELS, DEFAULT_CHAT_AGENT_MODE, type DefaultChatTransportEndpoints, type ExecutionConfirmationSubmission, type ExecutionProposal, type PlanQuestionOption, type PlanQuestionnaire, type PlanQuestionnaireSubmission, type ResultSummary, type TransformChatStreamPacket, createDefaultChatTransport, useChatContext, useChatStore };

package/dist/index.d.ts

@@ -101,6 +101,7 @@ interface PlanBooleanQuestion extends PlanQuestionBase {
  * Supported question variants in a plan questionnaire.
  */
 type PlanQuestion = PlanSingleSelectQuestion | PlanMultiSelectQuestion | PlanTextQuestion | PlanNumberQuestion | PlanBooleanQuestion;
+type PlanQuestionnaireStatus = 'expired' | 'failed';
 /**
  * Structured question form emitted for plan-mode clarification flows.
  */
@@ -111,6 +112,8 @@ interface PlanQuestionnaire {
     submitLabel?: string;
     questions: PlanQuestion[];
     answers?: Partial<Record<string, PlanQuestionnaireAnswerValue>>;
+    status?: PlanQuestionnaireStatus;
+    statusMessage?: string;
 }
 /**
  * Submission payload emitted by a questionnaire card.
@@ -129,6 +132,13 @@ interface ExecutionConfirmationSubmission {
     content: string;
     sourceMessageId?: string;
 }
+/**
+ * Context metadata provided to custom structured submission handlers.
+ */
+interface ChatSubmissionContext {
+    sessionId?: string;
+    mode: ChatAgentMode;
+}
 /**
  * Summary item used by structured assistant cards to describe parameter changes.
  */
@@ -142,22 +152,47 @@ interface ChatParameterSummaryItem {
  */
 interface ExecutionProposal {
     proposalId: string;
-    equationKey: string;
-    equationName: string;
-    solverName?: string;
+    resourceKey: string;
+    resourceName: string;
+    executorName?: string;
     parameterSummary: ChatParameterSummaryItem[];
     warnings?: string[];
     requiresConfirmation: true;
 }
 /**
- * Structured result summary emitted after a PDE task has started or completed.
+ * Structured result summary emitted after a task has started or completed.
  */
 interface ResultSummary {
-    taskId: string;
+    summaryId: string;
     status: 'completed' | 'failed' | 'running' | 'pending';
     headline: string;
     details: string[];
 }
+/**
+ * Merge behavior applied when a keyed custom block is patched repeatedly.
+ */
+type ChatCustomBlockMergePolicy = 'append' | 'replace' | 'ignore-duplicate';
+/**
+ * Extensible custom block rendered by a consumer-provided block renderer.
+ */
+interface ChatCustomBlock {
+    type: 'custom';
+    kind: string;
+    data: unknown;
+    /**
+     * Stable key used to identify the same logical block across streaming patches.
+     * When present, keyed custom blocks are merged by `blockKey` regardless of `kind`.
+     */
+    blockKey?: string;
+    /**
+     * Merge strategy used when another custom block with the same key arrives.
+     *
+     * - `append`: keep appending blocks even if the key matches.
+     * - `replace`: replace the existing keyed block with the latest one.
+     * - `ignore-duplicate`: keep the first keyed block and ignore later duplicates.
+     */
+    mergePolicy?: ChatCustomBlockMergePolicy;
+}
 /**
  * Structured assistant block variants rendered by the chat thread.
  */
@@ -180,11 +215,7 @@ type ChatMessageBlock = {
 } | {
     type: 'questionnaire';
     questionnaire: PlanQuestionnaire;
-} | {
-    type: 'custom';
-    kind: string;
-    data: unknown;
-};
+} | ChatCustomBlock;
 /**
  * Supported message body render orders for mixed text and structured blocks.
  */
@@ -279,6 +310,14 @@ interface ChatMessageBlockRendererProps {
  * Optional renderer used for custom block variants.
  */
 type ChatMessageBlockRenderer = (props: ChatMessageBlockRendererProps) => ReactNode;
+/**
+ * Optional application-provided handler that intercepts questionnaire submissions.
+ */
+type ChatQuestionnaireSubmitHandler = (submission: PlanQuestionnaireSubmission, context: ChatSubmissionContext) => Promise<boolean | void> | boolean | void;
+/**
+ * Optional application-provided handler that intercepts confirmation submissions.
+ */
+type ChatConfirmationSubmitHandler = (submission: ExecutionConfirmationSubmission, context: ChatSubmissionContext) => Promise<boolean | void> | boolean | void;
 interface ChatModel {
     id: string;
     object: string;
@@ -336,10 +375,18 @@ interface AiChatLabels {
     attachmentLimitNotice?: string;
     userRoleLabel?: string;
     assistantRoleLabel?: string;
+    expandMessageAriaLabel?: string;
+    collapseMessageAriaLabel?: string;
+    expandComposerAriaLabel?: string;
+    collapseComposerAriaLabel?: string;
     stoppedResponse?: string;
     assistantStreamingAriaLabel?: string;
     networkError?: string;
     genericError?: string;
+    questionnaireSubmitting?: string;
+    questionnaireSubmitted?: string;
+    questionnaireValidationPrefix?: string;
+    questionnaireSubmitFailed?: string;
 }
 /**
  * Default English label values used when no labels are provided.
@@ -353,6 +400,10 @@ interface AiChatProviderBaseProps {
     labels?: AiChatLabels;
     /** Optional renderer used to extend message blocks with app-specific UI. */
     renderMessageBlock?: ChatMessageBlockRenderer;
+    /** Optional handler used to intercept questionnaire submissions before the default send flow. */
+    handleQuestionnaireSubmit?: ChatQuestionnaireSubmitHandler;
+    /** Optional handler used to intercept confirmation submissions before the default send flow. */
+    handleConfirmationSubmit?: ChatConfirmationSubmitHandler;
     /** Optional render order used for mixed text and structured message blocks. */
     messageRenderOrder?: ChatMessageRenderOrder;
     /**
@@ -416,6 +467,17 @@ interface DefaultChatTransportEndpoints {
     /** Relative path used to request stream termination. */
     terminate?: string;
 }
+/**
+ * Tool execution policy applied to outgoing stream requests.
+ */
+interface ChatToolExecutionPolicy {
+    /** Enables tool execution headers for the stream request. */
+    enabled?: boolean;
+    /** Marks the request as requiring explicit approval before tool execution. */
+    approvalRequired?: boolean;
+    /** Approval timeout in seconds, forwarded when approval is enabled. */
+    approvalTimeoutSec?: number;
+}
 /**
  * Options for the built-in HTTP transport adapter.
  */
@@ -424,6 +486,8 @@ interface CreateDefaultChatTransportOptions {
     apiBaseUrl: string;
     /** Authorization header value forwarded to the backend. */
     authToken: string;
+    /** Optional tool execution policy translated into stream request headers. */
+    toolExecutionPolicy?: ChatToolExecutionPolicy;
     /** Optional extra headers appended to each streaming chat completion request. */
     streamHeaders?: Record<string, string>;
     /** Optional transformer used to normalize custom stream packets. */
@@ -436,7 +500,7 @@ interface CreateDefaultChatTransportOptions {
 /**
  * Creates the built-in transport backed by the current HTTP chat API.
  */
-declare const createDefaultChatTransport: ({ apiBaseUrl, authToken, streamHeaders, transformStreamPacket, endpoints, axiosInstance, }: CreateDefaultChatTransportOptions) => ChatTransport;
+declare const createDefaultChatTransport: ({ apiBaseUrl, authToken, toolExecutionPolicy, streamHeaders, transformStreamPacket, endpoints, axiosInstance, }: CreateDefaultChatTransportOptions) => ChatTransport;
 
 declare const ChatThread: () => _emotion_react_jsx_runtime.JSX.Element;
 
@@ -466,6 +530,8 @@ interface ChatComposerViewProps {
         plan: string;
         agent: string;
     };
+    expandComposerAriaLabel: string;
+    collapseComposerAriaLabel: string;
     onValueChange: (value: string) => void;
     onPickImages: (files: FileList | File[]) => void;
     onPasteImages: (files: File[]) => void;
@@ -529,6 +595,10 @@ interface ChatContextValue {
     retryRef: MutableRefObject<() => Promise<void>>;
     /** Optional block renderer used to extend message rendering with custom block types. */
     renderMessageBlock?: ChatMessageBlockRenderer;
+    /** Optional handler used to intercept questionnaire submissions before the default send flow. */
+    handleQuestionnaireSubmit?: ChatQuestionnaireSubmitHandler;
+    /** Optional handler used to intercept confirmation submissions before the default send flow. */
+    handleConfirmationSubmit?: ChatConfirmationSubmitHandler;
     /** Optional render order used for mixed text and structured message blocks. */
     messageRenderOrder?: ChatMessageRenderOrder;
     /** Optional packet transformer used by the legacy default adapter. */
@@ -551,4 +621,4 @@ declare const useChatContext: () => ChatContextValue;
  */
 declare const useChatStore: <T>(selector: (state: ChatStore) => T) => T;
 
-export { AiChat, type AiChatLabels, type AiChatProps, AiChatProvider, type AiChatProviderProps, CHAT_AGENT_MODES, CHAT_MESSAGE_RENDER_ORDERS, type ChatAgentMode, ChatComposer, type ChatComposerViewProps, ChatConversationList, type ChatImageAttachment, type ChatMessage, type ChatMessageBlock, type ChatMessageBlockRenderer, type ChatMessageBlockRendererProps, type ChatMessageRenderOrder, type ChatMessageStatus, type ChatModel, type ChatRole, type ChatSession, type ChatStreamMessagePatch, type ChatStreamPacketTransformArgs, type ChatStreamPacketUpdate, ChatThread, type ChatTransport, type ChatTransportStartStreamArgs, type CreateDefaultChatTransportOptions, DEFAULT_AI_CHAT_LABELS, DEFAULT_CHAT_AGENT_MODE, type DefaultChatTransportEndpoints, type ExecutionConfirmationSubmission, type ExecutionProposal, type PlanQuestionnaire, type PlanQuestionnaireSubmission, type ResultSummary, type TransformChatStreamPacket, createDefaultChatTransport, useChatContext, useChatStore };
+export { AiChat, type AiChatLabels, type AiChatProps, AiChatProvider, type AiChatProviderProps, CHAT_AGENT_MODES, CHAT_MESSAGE_RENDER_ORDERS, type ChatAgentMode, ChatComposer, type ChatComposerViewProps, type ChatConfirmationSubmitHandler, ChatConversationList, type ChatImageAttachment, type ChatMessage, type ChatMessageBlock, type ChatMessageBlockRenderer, type ChatMessageBlockRendererProps, type ChatMessageRenderOrder, type ChatMessageStatus, type ChatModel, type ChatParameterSummaryItem, type ChatQuestionnaireSubmitHandler, type ChatRole, type ChatSession, type ChatStreamMessagePatch, type ChatStreamPacketTransformArgs, type ChatStreamPacketUpdate, type ChatSubmissionContext, ChatThread, type ChatToolExecutionPolicy, type ChatTransport, type ChatTransportStartStreamArgs, type CreateDefaultChatTransportOptions, DEFAULT_AI_CHAT_LABELS, DEFAULT_CHAT_AGENT_MODE, type DefaultChatTransportEndpoints, type ExecutionConfirmationSubmission, type ExecutionProposal, type PlanQuestionOption, type PlanQuestionnaire, type PlanQuestionnaireSubmission, type ResultSummary, type TransformChatStreamPacket, createDefaultChatTransport, useChatContext, useChatStore };