@kortyx/hooks 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.18.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.17.1...hooks-v0.18.0) (2026-08-02)
+
+
+### Features
+
+* **studio:** release self-hosted observability preview ([4e9d3fd](https://github.com/kortyx-io/kortyx/commit/4e9d3fdbc7233f9b1de94ca1afe6dbae9cc9157f))
+* **studio:** release self-hosted observability preview ([#139](https://github.com/kortyx-io/kortyx/issues/139)) ([4e9d3fd](https://github.com/kortyx-io/kortyx/commit/4e9d3fdbc7233f9b1de94ca1afe6dbae9cc9157f))
+* **telemetry:** add persisted studio read models ([cebb06b](https://github.com/kortyx-io/kortyx/commit/cebb06bb74ccd4422e263f0ff4efa0fee5a16240))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/telemetry-contracts bumped to 0.2.0
+
+## [0.17.1](https://github.com/kortyx-io/kortyx/compare/hooks-v0.17.0...hooks-v0.17.1) (2026-05-28)
+
+
+### Bug Fixes
+
+* pass same metadata as useReason ([7b08754](https://github.com/kortyx-io/kortyx/commit/7b087542e54e9b0fe51bd3596a787dee41d5544a))
+* pass same metadata as useReason ([5540ef4](https://github.com/kortyx-io/kortyx/commit/5540ef4b0a339fd43b09721b826f6b01a670c2a7))
+
 ## [0.17.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.16.0...hooks-v0.17.0) (2026-05-26)
 
 

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,7 +1,8 @@
 import { NodeConfig, InterruptInput, InterruptResult, GraphState } from '@kortyx/core';
-import { R as ReasonTraceAdapter, K as KortyxTraceMetadata } from './tracing-DhjgeiDS.js';
-export { a as KortyxTelemetryConfig, b as KortyxTelemetryContentCapture, c as KortyxTelemetryPrompt, d as KortyxTraceAdapter, e as ReasonTraceAttributes, f as ReasonTraceSpan, g as ReasonTraceSpanEndArgs, h as ReasonTraceSpanStartArgs } from './tracing-DhjgeiDS.js';
+import { R as ReasonTraceAdapter, K as KortyxTraceMetadata } from './tracing-DeYHBpY1.js';
+export { E as EnsureWorkflowTopologyRequest, a as EnsureWorkflowTopologyResponse, b as KortyxTelemetryConfig, c as KortyxTelemetryContentCapture, d as KortyxTelemetryCorrelation, e as KortyxTelemetryEvent, f as KortyxTelemetryEventType, g as KortyxTelemetryPrompt, h as KortyxTelemetryReporter, i as KortyxTelemetryService, j as KortyxTraceAdapter, k as ReasonTraceAttributes, l as ReasonTraceSpan, m as ReasonTraceSpanEndArgs, n as ReasonTraceSpanStartArgs } from './tracing-DeYHBpY1.js';
 import { ProviderModelRef, KortyxReasoningOptions, KortyxResponseFormat, KortyxExecutableTool, KortyxUsage, KortyxFinishReason, KortyxProviderMetadata, KortyxWarning, KortyxToolCall, KortyxToolResult } from '@kortyx/providers';
+import '@kortyx/telemetry-contracts';
 
 type HookNodeRuntimeContext = {
     graph: {

package/dist/index.js

@@ -175,6 +175,48 @@ function getHookContext() {
   return ctx;
 }
 
+// src/reason/checkpoint.ts
+var resolveReasonCheckpointKey = (args) => typeof args.id === "string" && args.id.length > 0 ? `__useReason:${args.id}` : `__useReason:auto:${args.autoIndex}`;
+var readReasonCheckpoint = (raw) => {
+  if (!raw || typeof raw !== "object") return void 0;
+  const value = raw;
+  if (value.status !== "awaiting_interrupt") return void 0;
+  if (typeof value.firstText !== "string") return void 0;
+  if (!value.request || typeof value.request !== "object") return void 0;
+  return {
+    status: "awaiting_interrupt",
+    request: value.request,
+    firstText: value.firstText,
+    ...Object.hasOwn(value, "firstRaw") ? { firstRaw: value.firstRaw } : {},
+    ...Object.hasOwn(value, "firstUsage") ? { firstUsage: value.firstUsage } : {},
+    ...Object.hasOwn(value, "firstFinishReason") ? { firstFinishReason: value.firstFinishReason } : {},
+    ...Object.hasOwn(value, "firstProviderMetadata") ? {
+      firstProviderMetadata: value.firstProviderMetadata
+    } : {},
+    ...Object.hasOwn(value, "firstWarnings") ? { firstWarnings: value.firstWarnings } : {},
+    ...Object.hasOwn(value, "firstOutput") ? { firstOutput: value.firstOutput } : {}
+  };
+};
+var readReasonCompletedCheckpoint = (raw) => {
+  if (!raw || typeof raw !== "object") return void 0;
+  const value = raw;
+  if (value.status !== "completed") return void 0;
+  if (!value.result || typeof value.result !== "object") return void 0;
+  return {
+    status: "completed",
+    result: value.result
+  };
+};
+var resolveHookStatePatch = (args) => ({
+  __kortyx: {
+    nodeState: {
+      nodeId: args.nodeId,
+      state: args.currentNodeState
+    },
+    workflowState: args.workflowState
+  }
+});
+
 // src/validation.ts
 var parseWithSchema = (schema, value, label) => {
   if (!schema) return value;
@@ -193,12 +235,21 @@ var awaitInterruptInternal = (args) => {
     args.request,
     "useInterrupt request"
   );
+  const userMeta = args.meta && typeof args.meta === "object" && !Array.isArray(args.meta) ? args.meta : {};
+  const resumeStatePatch = resolveHookStatePatch({
+    nodeId: ctx.node.graph.node,
+    currentNodeState: ctx.currentNodeState,
+    workflowState: ctx.workflowState
+  });
   const enrichedRequest = {
     ...request,
     ...typeof args.schemaId === "string" && args.schemaId.length > 0 ? { schemaId: args.schemaId } : {},
     ...typeof args.schemaVersion === "string" && args.schemaVersion.length > 0 ? { schemaVersion: args.schemaVersion } : {},
     ...typeof args.id === "string" && args.id.length > 0 ? { id: args.id } : {},
-    ...args.meta && typeof args.meta === "object" && !Array.isArray(args.meta) ? { meta: args.meta } : {}
+    meta: {
+      ...userMeta,
+      __kortyxResumeStatePatch: resumeStatePatch
+    }
   };
   const raw = ctx.node.awaitInterrupt(enrichedRequest);
   const response = parseWithSchema(
@@ -301,48 +352,6 @@ var emitStructuredData = (args) => {
 var shouldEmitStructured = (cfg) => Boolean(cfg);
 var shouldStreamStructured = (cfg) => Boolean(cfg) && (cfg?.stream ?? true);
 
-// src/reason/checkpoint.ts
-var resolveReasonCheckpointKey = (args) => typeof args.id === "string" && args.id.length > 0 ? `__useReason:${args.id}` : `__useReason:auto:${args.autoIndex}`;
-var readReasonCheckpoint = (raw) => {
-  if (!raw || typeof raw !== "object") return void 0;
-  const value = raw;
-  if (value.status !== "awaiting_interrupt") return void 0;
-  if (typeof value.firstText !== "string") return void 0;
-  if (!value.request || typeof value.request !== "object") return void 0;
-  return {
-    status: "awaiting_interrupt",
-    request: value.request,
-    firstText: value.firstText,
-    ...Object.hasOwn(value, "firstRaw") ? { firstRaw: value.firstRaw } : {},
-    ...Object.hasOwn(value, "firstUsage") ? { firstUsage: value.firstUsage } : {},
-    ...Object.hasOwn(value, "firstFinishReason") ? { firstFinishReason: value.firstFinishReason } : {},
-    ...Object.hasOwn(value, "firstProviderMetadata") ? {
-      firstProviderMetadata: value.firstProviderMetadata
-    } : {},
-    ...Object.hasOwn(value, "firstWarnings") ? { firstWarnings: value.firstWarnings } : {},
-    ...Object.hasOwn(value, "firstOutput") ? { firstOutput: value.firstOutput } : {}
-  };
-};
-var readReasonCompletedCheckpoint = (raw) => {
-  if (!raw || typeof raw !== "object") return void 0;
-  const value = raw;
-  if (value.status !== "completed") return void 0;
-  if (!value.result || typeof value.result !== "object") return void 0;
-  return {
-    status: "completed",
-    result: value.result
-  };
-};
-var resolveHookStatePatch = (args) => ({
-  __kortyx: {
-    nodeState: {
-      nodeId: args.nodeId,
-      state: args.currentNodeState
-    },
-    workflowState: args.workflowState
-  }
-});
-
 // src/reason/engine.ts
 var import_node_crypto3 = require("crypto");
 
@@ -415,6 +424,17 @@ async function runReasonEngine(args) {
       input: args.telemetry?.input ?? messages
     }
   });
+  const modelRequestStartedAt = Date.now();
+  let firstTextTokenAt;
+  let lastTextTokenAt;
+  const generationTimingAttributes = () => firstTextTokenAt === void 0 || lastTextTokenAt === void 0 ? {} : {
+    ttftMs: Math.max(0, firstTextTokenAt - modelRequestStartedAt),
+    streamDurationMs: Math.max(0, lastTextTokenAt - firstTextTokenAt),
+    timeToLastTokenMs: Math.max(
+      0,
+      lastTextTokenAt - modelRequestStartedAt
+    )
+  };
   const endTrace = (span, result) => {
     span?.end?.({
       ...result.usage !== void 0 ? { usage: result.usage } : {},
@@ -422,7 +442,8 @@ async function runReasonEngine(args) {
       ...result.providerMetadata !== void 0 ? { providerMetadata: result.providerMetadata } : {},
       ...result.warnings !== void 0 ? { warnings: result.warnings } : {},
       attributes: {
-        textLength: result.text.length
+        textLength: result.text.length,
+        ...generationTimingAttributes()
       },
       telemetry: {
         ...args.telemetry ?? {},
@@ -457,6 +478,9 @@ async function runReasonEngine(args) {
         switch (chunk.type) {
           case "text-delta": {
             if (chunk.delta.length === 0) break;
+            const tokenAt = Date.now();
+            firstTextTokenAt ??= tokenAt;
+            lastTextTokenAt = tokenAt;
             final += chunk.delta;
             args.onTextChunk?.(chunk.delta);
             if (chunk.raw !== void 0) {
@@ -1700,6 +1724,11 @@ var runReasonToolLoop = async (args) => {
           tool.name,
           false
         );
+        traceSpan?.addEvent?.("useReason.tool-call.start", {
+          stepIndex,
+          tool: tool.name,
+          toolCallId: toolCall.id
+        });
         if (shouldEmitTool) {
           emitToolEvent("tool-call-start", {
             tool: tool.name,