@kortyx/react 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @kortyx/react
 
+## [0.5.0](https://github.com/kortyx-io/kortyx/compare/react-v0.4.3...react-v0.5.0) (2026-09-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* **errors:** public failure messages and default HTTP statuses change; malformed streams fail explicitly, provider error classes are shared, and retry helpers exclude control flow. Existing calls and legacy records remain supported. See the error-contract migration and release notes.
+
+### Features
+
+* **errors:** harden failure contracts across execution and recovery ([#175](https://github.com/kortyx-io/kortyx/issues/175)) ([d231e36](https://github.com/kortyx-io/kortyx/commit/d231e364259a4f23fc3675d8783fde5ba338416e))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/stream bumped to 0.12.0
+    * @kortyx/core bumped to 0.9.0
+
+## [0.4.3](https://github.com/kortyx-io/kortyx/compare/react-v0.4.2...react-v0.4.3) (2026-09-10)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/stream bumped to 0.11.0
+
+## [0.4.2](https://github.com/kortyx-io/kortyx/compare/react-v0.4.1...react-v0.4.2) (2026-09-10)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/stream bumped to 0.10.0
+
 ## [0.4.1](https://github.com/kortyx-io/kortyx/compare/react-v0.4.0...react-v0.4.1) (2026-06-03)
 
 

package/LICENSE

@@ -1,10 +1,18 @@
+Copyright 2026 Kortyx contributors
+
+Portions of this software are licensed as follows:
+
+- All content that resides under the `apps/studio/` directory of this repository is licensed under the license defined in `apps/studio/LICENSE.md`.
+- All content that resides under a `plugins/*/` directory of this repository is licensed under the license defined in that plugin's `LICENSE.md`.
+- All third party components incorporated into the Kortyx software are licensed under the original license provided by the owner of the applicable component.
+- Content outside of the above mentioned directories or restrictions is available under the Apache License, Version 2.0, as defined below.
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
 
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
+  TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+  1.  Definitions.
 
       "License" shall mean the terms and conditions for use, reproduction,
       and distribution as defined by Sections 1 through 9 of this document.
@@ -63,14 +71,14 @@
       on behalf of whom a Contribution has been received by Licensor and
       subsequently incorporated within the Work.
 
-   2. Grant of Copyright License. Subject to the terms and conditions of
+  2.  Grant of Copyright License. Subject to the terms and conditions of
       this License, each Contributor hereby grants to You a perpetual,
       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
       copyright license to reproduce, prepare Derivative Works of,
       publicly display, publicly perform, sublicense, and distribute the
       Work and such Derivative Works in Source or Object form.
 
-   3. Grant of Patent License. Subject to the terms and conditions of
+  3.  Grant of Patent License. Subject to the terms and conditions of
       this License, each Contributor hereby grants to You a perpetual,
       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
       (except as stated in this section) patent license to make, have made,
@@ -86,39 +94,39 @@
       granted to You under this License for that Work shall terminate
       as of the date such litigation is filed.
 
-   4. Redistribution. You may reproduce and distribute copies of the
+  4.  Redistribution. You may reproduce and distribute copies of the
       Work or Derivative Works thereof in any medium, with or without
       modifications, and in Source or Object form, provided that You
       meet the following conditions:
 
       (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
+      Derivative Works a copy of this License; and
 
       (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
+      stating that You changed the files; and
 
       (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
+      that You distribute, all copyright, patent, trademark, and
+      attribution notices from the Source form of the Work,
+      excluding those notices that do not pertain to any part of
+      the Derivative Works; and
 
       (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
+      distribution, then any Derivative Works that You distribute must
+      include a readable copy of the attribution notices contained
+      within such NOTICE file, excluding those notices that do not
+      pertain to any part of the Derivative Works, in at least one
+      of the following places: within a NOTICE text file distributed
+      as part of the Derivative Works; within the Source form or
+      documentation, if provided along with the Derivative Works; or,
+      within a display generated by the Derivative Works, if and
+      wherever such third-party notices normally appear. The contents
+      of the NOTICE file are for informational purposes only and
+      do not modify the License. You may add Your own attribution
+      notices within Derivative Works that You distribute, alongside
+      or as an addendum to the NOTICE text from the Work, provided
+      that such additional attribution notices cannot be construed
+      as modifying the License.
 
       You may add Your own copyright statement to Your modifications and
       may provide additional or different license terms and conditions
@@ -127,7 +135,7 @@
       reproduction, and distribution of the Work otherwise complies with
       the conditions stated in this License.
 
-   5. Submission of Contributions. Unless You explicitly state otherwise,
+  5.  Submission of Contributions. Unless You explicitly state otherwise,
       any Contribution intentionally submitted for inclusion in the Work
       by You to the Licensor shall be under the terms and conditions of
       this License, without any additional terms or conditions.
@@ -135,12 +143,12 @@
       the terms of any separate license agreement you may have executed
       with Licensor regarding such Contributions.
 
-   6. Trademarks. This License does not grant permission to use the trade
+  6.  Trademarks. This License does not grant permission to use the trade
       names, trademarks, service marks, or product names of the Licensor,
       except as required for reasonable and customary use in describing the
       origin of the Work and reproducing the content of the NOTICE file.
 
-   7. Disclaimer of Warranty. Unless required by applicable law or
+  7.  Disclaimer of Warranty. Unless required by applicable law or
       agreed to in writing, Licensor provides the Work (and each
       Contributor provides its Contributions) on an "AS IS" BASIS,
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
@@ -150,7 +158,7 @@
       appropriateness of using or redistributing the Work and assume any
       risks associated with Your exercise of permissions under this License.
 
-   8. Limitation of Liability. In no event and under no legal theory,
+  8.  Limitation of Liability. In no event and under no legal theory,
       whether in tort (including negligence), contract, or otherwise,
       unless required by applicable law (such as deliberate and grossly
       negligent acts) or agreed to in writing, shall any Contributor be
@@ -162,7 +170,7 @@
       other commercial damages or losses), even if such Contributor
       has been advised of the possibility of such damages.
 
-   9. Accepting Warranty or Additional Liability. While redistributing
+  9.  Accepting Warranty or Additional Liability. While redistributing
       the Work or Derivative Works thereof, You may choose to offer,
       and charge a fee for, acceptance of support, warranty, indemnity,
       or other liability obligations and/or rights consistent with this
@@ -173,9 +181,9 @@
       incurred by, or claims asserted against, such Contributor by reason
       of your accepting any such warranty or additional liability.
 
-   END OF TERMS AND CONDITIONS
+  END OF TERMS AND CONDITIONS
 
-   APPENDIX: How to apply the Apache License to your work.
+  APPENDIX: How to apply the Apache License to your work.
 
       To apply the Apache License to your work, attach the following
       boilerplate notice, with the fields enclosed by brackets "[]"
@@ -186,16 +194,16 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+  Copyright [yyyy] [name of copyright owner]
 
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
 
        http://www.apache.org/licenses/LICENSE-2.0
 
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { StructuredStreamState, StreamChunk, StreamFromRouteArgs, StructuredDataChunk } from '@kortyx/stream/browser';
+import * as _kortyx_core_errors from '@kortyx/core/errors';
+import { FailureDescriptor } from '@kortyx/core/errors';
 
 type StructuredData = StructuredStreamState<Record<string, unknown>>;
 type HumanInputPiece = {
@@ -31,6 +33,7 @@ type ContentPiece = {
     id: string;
     type: "error";
     content: string;
+    failure?: FailureDescriptor;
 } | HumanInputPiece;
 type ChatMsg = {
     id: string;
@@ -41,6 +44,17 @@ type ChatMsg = {
     traceId?: string;
     spanId?: string;
     runId?: string;
+    checkpointId?: string;
+    checkpointTurnIndex?: number;
+    source?: {
+        type: "prompt";
+    } | {
+        type: "interrupt-response";
+        resumeToken: string;
+        requestId: string;
+        selected: string[];
+        text?: string;
+    };
 };
 
 declare function buildAssistantMessage(args: {
@@ -52,6 +66,10 @@ declare function buildAssistantMessage(args: {
         spanId: string;
         runId: string;
     } | undefined;
+    checkpoint?: {
+        id: string;
+        turnIndex: number;
+    } | undefined;
 }): ChatMsg;
 
 type MaybePromise$1<T> = T | Promise<T>;
@@ -60,6 +78,14 @@ type PersistedChatState<TMessage> = {
     workflowId: string;
     includeHistory: boolean;
     messages: TMessage[];
+    branches?: Record<string, {
+        sessionId: string;
+        parentSessionId?: string;
+        forkedFrom?: string;
+        messages: TMessage[];
+        checkpoints?: unknown[];
+    }>;
+    responseVariants?: unknown[];
 };
 type ChatStorage<TMessage> = {
     load: () => MaybePromise$1<Partial<PersistedChatState<TMessage>>>;
@@ -71,6 +97,8 @@ type BrowserChatStorageKeys = {
     includeHistory: string;
     sessionId: string;
     workflowId: string;
+    branches: string;
+    responseVariants: string;
 };
 type BrowserChatStorageOptions<TMessage> = {
     parseMessage?: ((value: unknown) => TMessage | null) | undefined;
@@ -95,10 +123,59 @@ type ChatTransportContext<TContext = DefaultChatContext$1> = {
     signal?: AbortSignal | undefined;
 };
 type ChatTransportChunkHandler = (chunk: StreamChunk) => undefined | boolean | Promise<boolean | undefined>;
+type CheckpointSummary = {
+    id: string;
+    sessionId: string;
+    turnIndex: number;
+    createdAt: number;
+    nodes: string[];
+    workflow: string;
+    label?: string;
+};
+type RollbackCheckpointResult = {
+    sessionId: string;
+    head: string;
+    invalidatedStructuredStreamIds: string[];
+    invalidatedInterruptTokens: string[];
+};
+type ForkPendingRequest = {
+    token: string;
+    requestId: string;
+    schema?: {
+        kind?: "choice" | "multi-choice" | "text";
+        multiple?: boolean;
+        question?: string;
+        id?: string;
+        schemaId?: string;
+        schemaVersion?: string;
+        meta?: Record<string, unknown>;
+    };
+    options?: Array<{
+        id: string;
+        label: string;
+        description?: string;
+    }>;
+};
+type ForkCheckpointResult = {
+    sessionId: string;
+    parentSessionId: string;
+    forkedFrom: string;
+    checkpoint?: {
+        id: string;
+        sessionId: string;
+        turnIndex: number;
+        activePendingRequests?: ForkPendingRequest[];
+    };
+};
 type ChatTransport<TContext = DefaultChatContext$1> = {
     stream(args: ChatTransportContext<TContext> & {
         onChunk: ChatTransportChunkHandler;
     }): Promise<void>;
+    listCheckpoints?: (sessionId: string) => Promise<CheckpointSummary[]>;
+    rollbackTo?: (checkpointId: string) => Promise<RollbackCheckpointResult>;
+    fork?: (checkpointId: string, options?: {
+        newSessionId?: string;
+    }) => Promise<ForkCheckpointResult>;
 };
 type ChatTransportChunkSource = Iterable<StreamChunk> | AsyncIterable<StreamChunk>;
 declare function createChatTransport<TContext = DefaultChatContext$1>(args: {
@@ -112,6 +189,7 @@ type RouteChatRequestBody<TContext = DefaultChatContext$1> = {
 };
 type CreateRouteChatTransportArgs<TBody, TContext> = Omit<StreamFromRouteArgs<TBody>, "body"> & {
     createBody?: ((context: ChatTransportContext<TContext>) => TBody) | undefined;
+    checkpointEndpoint?: string | undefined;
 };
 declare function createRouteChatTransport<TContext = DefaultChatContext$1, TBody = RouteChatRequestBody<TContext>>(args: CreateRouteChatTransportArgs<TBody, TContext>): ChatTransport<TContext>;
 
@@ -130,6 +208,7 @@ type UseStructuredStreamsResult<TData = unknown> = {
     applyStreamChunk: (chunk: StreamChunk) => StructuredStreamItem<TData> | undefined;
     clear: () => void;
     get: (streamId: string) => StructuredStreamItem<TData> | undefined;
+    delete: (streamId: string) => boolean;
 };
 declare function useStructuredStreams<TData = unknown>(options?: UseStructuredStreamsOptions<TData> | undefined): UseStructuredStreamsResult<TData>;
 
@@ -146,6 +225,7 @@ type LiveChatStructuredPiece<TStructuredData = unknown> = {
 type LiveChatErrorPiece = {
     id: string;
     type: "error";
+    failure?: FailureDescriptor;
     content: string;
 };
 type LiveChatCustomPiece = {
@@ -194,6 +274,10 @@ type UseChatValue = {
     streamContentPieces: ContentPiece[];
     streamDebug: StreamChunk[];
     lastAssistantId: string | null;
+    checkpoints: CheckpointSummary[];
+    activeSessionId: string | null;
+    branches: Record<string, ChatBranch>;
+    responseVariants: ChatResponseVariantGroup[];
     workflowId: string;
     setWorkflowId: React.Dispatch<React.SetStateAction<string>>;
     send: (text: string) => Promise<void> | void;
@@ -208,6 +292,17 @@ type UseChatValue = {
         text?: string | undefined;
     }) => Promise<void> | void;
     setMessages: React.Dispatch<React.SetStateAction<ChatMsg[]>>;
+    checkpointForMessage: (messageId: string) => string | null;
+    rollbackTo: (id: string) => Promise<RollbackCheckpointResult>;
+    fork: (id: string, options?: {
+        newSessionId?: string;
+    }) => Promise<ForkCheckpointResult>;
+    regenerate: (assistantMessageId: string) => Promise<void>;
+    regenerateVariant: (assistantMessageId: string) => Promise<ChatResponseVariantGroup>;
+    selectVariant: (assistantMessageId: string, variantId: string) => Promise<void>;
+    variantForMessage: (messageId: string) => ChatResponseVariantGroup | null;
+    regenerateFromCheckpoint: (checkpointId: string) => Promise<void>;
+    retryWithEdit: (assistantMessageId: string, newUserContent: string) => Promise<void>;
     clearMessages: () => void;
     resetSession: () => void;
     resetChat: () => void;
@@ -217,6 +312,32 @@ type UseChatValue = {
     includeHistory: boolean;
     setIncludeHistory: React.Dispatch<React.SetStateAction<boolean>>;
 };
+type ChatBranch<TMessage = ChatMsg> = {
+    sessionId: string;
+    parentSessionId?: string;
+    forkedFrom?: string;
+    messages: TMessage[];
+    checkpoints: CheckpointSummary[];
+};
+type ChatResponseVariant = {
+    id: string;
+    sessionId: string;
+    assistantMessageId: string;
+    createdAt: number;
+    messages: ChatMsg[];
+    checkpoints: CheckpointSummary[];
+    checkpointId?: string;
+    checkpointTurnIndex?: number;
+    label?: string;
+};
+type ChatResponseVariantGroup = {
+    id: string;
+    sourceAssistantMessageId: string;
+    checkpointId: string;
+    checkpointTurnIndex: number;
+    selectedVariantId: string;
+    variants: ChatResponseVariant[];
+};
 type UseChatOptions<TContext = DefaultChatContext> = {
     transport: ChatTransport<TContext>;
     storage?: ChatStorage<ChatMsg> | undefined;
@@ -231,6 +352,16 @@ declare function useChatStreamDebug(): {
     streamDebug: ({
         type: "session";
         sessionId: string;
+    } | {
+        type: "checkpoint";
+        id: string;
+        sessionId: string;
+        turnIndex: number;
+        label?: string;
+    } | {
+        type: "structured-data-invalidated";
+        streamId: string;
+        checkpointId: string;
     } | {
         type: "trace";
         traceId: string;
@@ -292,6 +423,7 @@ declare function useChatStreamDebug(): {
         tool: string;
         toolCallId: string;
         message: string;
+        failure?: _kortyx_core_errors.FailureDescriptor;
         node?: string;
         id?: string;
         opId?: string;
@@ -376,12 +508,23 @@ declare function useChatStreamDebug(): {
         type: "transition";
         transitionTo: string;
         payload?: any;
+    } | {
+        type: "limit-reached";
+        runId: string;
+        limit: "maxNodeExecutions" | "maxModelPasses" | "maxToolCalls" | "maxChildInvocations";
+        maximum: number;
+        consumed: number;
+    } | {
+        type: "cancelled";
+        runId: string;
+        reason: string;
     } | {
         type: "done";
         data?: any;
     } | {
         type: "error";
         message: string;
+        failure?: _kortyx_core_errors.FailureDescriptor;
     })[];
     clearStreamDebug: () => void;
     createRecorder: (initialMessage: string) => {
@@ -389,6 +532,16 @@ declare function useChatStreamDebug(): {
         getAll: () => ({
             type: "session";
             sessionId: string;
+        } | {
+            type: "checkpoint";
+            id: string;
+            sessionId: string;
+            turnIndex: number;
+            label?: string;
+        } | {
+            type: "structured-data-invalidated";
+            streamId: string;
+            checkpointId: string;
         } | {
             type: "trace";
             traceId: string;
@@ -450,6 +603,7 @@ declare function useChatStreamDebug(): {
             tool: string;
             toolCallId: string;
             message: string;
+            failure?: _kortyx_core_errors.FailureDescriptor;
             node?: string;
             id?: string;
             opId?: string;
@@ -534,14 +688,25 @@ declare function useChatStreamDebug(): {
             type: "transition";
             transitionTo: string;
             payload?: any;
+        } | {
+            type: "limit-reached";
+            runId: string;
+            limit: "maxNodeExecutions" | "maxModelPasses" | "maxToolCalls" | "maxChildInvocations";
+            maximum: number;
+            consumed: number;
+        } | {
+            type: "cancelled";
+            runId: string;
+            reason: string;
         } | {
             type: "done";
             data?: any;
         } | {
             type: "error";
             message: string;
+            failure?: _kortyx_core_errors.FailureDescriptor;
         })[];
     };
 };
 
-export { type BrowserChatStorageKeys, type BrowserChatStorageOptions, type ChatMsg, type ChatStorage, type ChatTransport, type ChatTransportChunkHandler, type ChatTransportChunkSource, type ChatTransportContext, type ContentPiece, type CreateRouteChatTransportArgs, type HumanInputPiece, type LiveChatErrorPiece, type LiveChatPiece, type LiveChatStructuredPiece, type LiveChatTextPiece, type OutgoingChatMessage, type PersistedChatState, type PrepareContextMessages, type PrepareContextMessagesArgs, type RouteChatRequestBody, type StructuredData, type StructuredStreamItem, type ToHumanInputPiece, type UseChatOptions, type UseChatValue, type UseStructuredStreamsOptions, type UseStructuredStreamsResult, buildAssistantMessage, createBrowserChatStorage, createChatTransport, createLiveChatPieces, createRouteChatTransport, toHumanInputPiece, useChat, useChatStreamDebug, useStructuredStreams };
+export { type BrowserChatStorageKeys, type BrowserChatStorageOptions, type ChatBranch, type ChatMsg, type ChatResponseVariant, type ChatResponseVariantGroup, type ChatStorage, type ChatTransport, type ChatTransportChunkHandler, type ChatTransportChunkSource, type ChatTransportContext, type CheckpointSummary, type ContentPiece, type CreateRouteChatTransportArgs, type ForkCheckpointResult, type ForkPendingRequest, type HumanInputPiece, type LiveChatErrorPiece, type LiveChatPiece, type LiveChatStructuredPiece, type LiveChatTextPiece, type OutgoingChatMessage, type PersistedChatState, type PrepareContextMessages, type PrepareContextMessagesArgs, type RollbackCheckpointResult, type RouteChatRequestBody, type StructuredData, type StructuredStreamItem, type ToHumanInputPiece, type UseChatOptions, type UseChatValue, type UseStructuredStreamsOptions, type UseStructuredStreamsResult, buildAssistantMessage, createBrowserChatStorage, createChatTransport, createLiveChatPieces, createRouteChatTransport, toHumanInputPiece, useChat, useChatStreamDebug, useStructuredStreams };