@kortyx/hooks 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.4.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.3.0...hooks-v0.4.0) (2026-02-17)
+
+
+### Features
+
+* **agent:** strict createAgent and unify useReason streaming ([6725f97](https://github.com/kortyx-io/kortyx/commit/6725f976fc32083fb7d2590f1353d16a99afb46f))
+
+
+### Bug Fixes
+
+* **hooks:** move reason engine to internal subpath export ([b82f2f2](https://github.com/kortyx-io/kortyx/commit/b82f2f2a93067f91dd010334486eb0f3a3a547b8))
+
 ## [0.3.0](https://github.com/kortyx-io/Kortyx/compare/hooks-v0.2.3...hooks-v0.3.0) (2026-02-07)
 
 

package/dist/hooks.d.ts

@@ -1,25 +1,25 @@
 import type { InterruptInput, InterruptResult, NodeContext } from "@kortyx/core";
 import type { MemoryAdapter } from "@kortyx/memory";
+import type { ProviderModelRef } from "@kortyx/providers";
 type StateSetter<T> = (next: T | ((prev: T) => T)) => void;
-export type AiCallArgs = {
-    prompt: string;
+export type UseReasonArgs = {
+    model: ProviderModelRef;
+    input: string;
     system?: string | undefined;
     temperature?: number | undefined;
     emit?: boolean | undefined;
     stream?: boolean | undefined;
 };
-export type AiCallResult = {
+export type UseReasonResult = {
     text: string;
-};
-export type AiModel = {
-    call: (args: AiCallArgs) => Promise<AiCallResult>;
+    raw?: unknown;
 };
 export declare function useEmit(): NodeContext["emit"];
 export declare function useStructuredData(args: {
     data: unknown;
     dataType?: string | undefined;
 }): void;
-export declare function useAiProvider(modelId?: string): AiModel;
+export declare function useReason(args: UseReasonArgs): Promise<UseReasonResult>;
 export declare function useAiMemory(): MemoryAdapter;
 export declare function useAiInterrupt(input: InterruptInput): Promise<InterruptResult>;
 export declare function useNodeState<T>(initialValue: T): [T, StateSetter<T>];

package/dist/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EAEf,WAAW,EACZ,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC;AA6C3D,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CACnD,CAAC;AAEF,wBAAgB,OAAO,IAAI,WAAW,CAAC,MAAM,CAAC,CAG7C;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B,GAAG,IAAI,CASP;AAED,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAoCvD;AAED,wBAAgB,WAAW,IAAI,aAAa,CAM3C;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,eAAe,CAAC,CAG1B;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AACtE,wBAAgB,YAAY,CAAC,CAAC,EAC5B,GAAG,EAAE,MAAM,EACX,YAAY,CAAC,EAAE,CAAC,GACf,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AA+CvB,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,GAAG,EAAE,MAAM,EACX,YAAY,CAAC,EAAE,CAAC,GACf,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAoBrB"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,WAAW,EACZ,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAK1D,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC;AAE3D,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,gBAAgB,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,wBAAgB,OAAO,IAAI,WAAW,CAAC,MAAM,CAAC,CAG7C;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B,GAAG,IAAI,CASP;AAyBD,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAEvE;AAED,wBAAgB,WAAW,IAAI,aAAa,CAM3C;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,eAAe,CAAC,CAG1B;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AACtE,wBAAgB,YAAY,CAAC,CAAC,EAC5B,GAAG,EAAE,MAAM,EACX,YAAY,CAAC,EAAE,CAAC,GACf,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AA+CvB,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,GAAG,EAAE,MAAM,EACX,YAAY,CAAC,EAAE,CAAC,GACf,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAoBrB"}

package/dist/hooks.js

@@ -2,40 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useEmit = useEmit;
 exports.useStructuredData = useStructuredData;
-exports.useAiProvider = useAiProvider;
+exports.useReason = useReason;
 exports.useAiMemory = useAiMemory;
 exports.useAiInterrupt = useAiInterrupt;
 exports.useNodeState = useNodeState;
 exports.useWorkflowState = useWorkflowState;
 const context_1 = require("./context");
-const DEFAULT_PROVIDER = "google";
-const DEFAULT_MODEL = "gemini-2.5-flash";
-const resolveModel = (modelId, config) => {
-    const defaultProvider = config?.provider ?? DEFAULT_PROVIDER;
-    const defaultModel = config?.name ?? DEFAULT_MODEL;
-    if (!modelId) {
-        return {
-            provider: defaultProvider,
-            name: defaultModel,
-            temperature: config?.temperature,
-        };
-    }
-    const separatorIndex = modelId.indexOf(":");
-    if (separatorIndex === -1) {
-        return {
-            provider: defaultProvider,
-            name: modelId,
-            temperature: config?.temperature,
-        };
-    }
-    const provider = modelId.slice(0, separatorIndex) || defaultProvider;
-    const name = modelId.slice(separatorIndex + 1) || defaultModel;
-    return {
-        provider,
-        name,
-        temperature: config?.temperature,
-    };
-};
+const reason_engine_1 = require("./reason-engine");
 function useEmit() {
     const ctx = (0, context_1.getHookContext)();
     return ctx.node.emit;
@@ -50,35 +23,27 @@ function useStructuredData(args) {
         data: args.data,
     });
 }
-function useAiProvider(modelId) {
+async function reasonEngine(args) {
     const ctx = (0, context_1.getHookContext)();
     const getProvider = ctx.getProvider;
     if (!getProvider) {
-        throw new Error("useAiProvider requires a provider factory in runtime config.");
+        throw new Error("useReason requires a provider factory in runtime config.");
     }
-    const { provider, name, temperature } = resolveModel(modelId, ctx.node.config?.model);
-    return {
-        call: async ({ prompt, system, temperature: overrideTemperature }) => {
-            if (!ctx.node.speak) {
-                throw new Error("useAiProvider requires ctx.speak in NodeContext.");
-            }
-            const text = await ctx.node.speak({
-                ...(typeof system === "string" && system.length > 0 ? { system } : {}),
-                user: prompt,
-                model: {
-                    provider,
-                    name,
-                    ...(overrideTemperature !== undefined
-                        ? { temperature: overrideTemperature }
-                        : temperature !== undefined
-                            ? { temperature }
-                            : {}),
-                },
-                stream: { minChars: 12, flushMs: 50, segmentChars: 48 },
-            });
-            return { text };
-        },
-    };
+    return (0, reason_engine_1.runReasonEngine)({
+        getProvider,
+        model: args.model,
+        input: args.input,
+        system: args.system,
+        temperature: args.temperature,
+        defaultTemperature: ctx.node.config?.model?.temperature,
+        stream: args.stream,
+        emit: args.emit,
+        nodeId: ctx.node.graph.node,
+        emitEvent: ctx.node.emit,
+    });
+}
+function useReason(args) {
+    return reasonEngine(args);
 }
 function useAiMemory() {
     const ctx = (0, context_1.getHookContext)();

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export type { HookRuntimeContext } from "./context";
 export { runWithHookContext } from "./context";
-export { useAiInterrupt, useAiMemory, useAiProvider, useEmit, useNodeState, useStructuredData, useWorkflowState, } from "./hooks";
+export type { UseReasonArgs, UseReasonResult } from "./hooks";
+export { useAiInterrupt, useAiMemory, useEmit, useNodeState, useReason, useStructuredData, useWorkflowState, } from "./hooks";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EACL,cAAc,EACd,WAAW,EACX,aAAa,EACb,OAAO,EACP,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EACL,cAAc,EACd,WAAW,EACX,OAAO,EACP,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,13 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useWorkflowState = exports.useStructuredData = exports.useNodeState = exports.useEmit = exports.useAiProvider = exports.useAiMemory = exports.useAiInterrupt = exports.runWithHookContext = void 0;
+exports.useWorkflowState = exports.useStructuredData = exports.useReason = exports.useNodeState = exports.useEmit = exports.useAiMemory = exports.useAiInterrupt = exports.runWithHookContext = void 0;
 var context_1 = require("./context");
 Object.defineProperty(exports, "runWithHookContext", { enumerable: true, get: function () { return context_1.runWithHookContext; } });
 var hooks_1 = require("./hooks");
 Object.defineProperty(exports, "useAiInterrupt", { enumerable: true, get: function () { return hooks_1.useAiInterrupt; } });
 Object.defineProperty(exports, "useAiMemory", { enumerable: true, get: function () { return hooks_1.useAiMemory; } });
-Object.defineProperty(exports, "useAiProvider", { enumerable: true, get: function () { return hooks_1.useAiProvider; } });
 Object.defineProperty(exports, "useEmit", { enumerable: true, get: function () { return hooks_1.useEmit; } });
 Object.defineProperty(exports, "useNodeState", { enumerable: true, get: function () { return hooks_1.useNodeState; } });
+Object.defineProperty(exports, "useReason", { enumerable: true, get: function () { return hooks_1.useReason; } });
 Object.defineProperty(exports, "useStructuredData", { enumerable: true, get: function () { return hooks_1.useStructuredData; } });
 Object.defineProperty(exports, "useWorkflowState", { enumerable: true, get: function () { return hooks_1.useWorkflowState; } });

package/dist/internal.d.ts

@@ -0,0 +1,3 @@
+export type { RunReasonEngineArgs, RunReasonEngineResult, } from "./reason-engine";
+export { runReasonEngine } from "./reason-engine";
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/internal.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runReasonEngine = void 0;
+var reason_engine_1 = require("./reason-engine");
+Object.defineProperty(exports, "runReasonEngine", { enumerable: true, get: function () { return reason_engine_1.runReasonEngine; } });

package/dist/reason-engine.d.ts

@@ -0,0 +1,19 @@
+import type { GetProviderFn, ProviderModelRef } from "@kortyx/providers";
+export interface RunReasonEngineArgs {
+    getProvider: GetProviderFn;
+    model: ProviderModelRef;
+    input: string;
+    system?: string | undefined;
+    temperature?: number | undefined;
+    defaultTemperature?: number | undefined;
+    stream?: boolean | undefined;
+    emit?: boolean | undefined;
+    nodeId?: string | undefined;
+    emitEvent?: ((event: string, payload: unknown) => void) | undefined;
+}
+export interface RunReasonEngineResult {
+    text: string;
+    raw?: unknown;
+}
+export declare function runReasonEngine(args: RunReasonEngineArgs): Promise<RunReasonEngineResult>;
+//# sourceMappingURL=reason-engine.d.ts.map

package/dist/reason-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reason-engine.d.ts","sourceRoot":"","sources":["../src/reason-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EAGb,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,aAAa,CAAC;IAC3B,KAAK,EAAE,gBAAgB,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,SAAS,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACrE;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAwBD,wBAAsB,eAAe,CACnC,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,qBAAqB,CAAC,CAoEhC"}

package/dist/reason-engine.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runReasonEngine = runReasonEngine;
+const chunkToText = (chunk) => {
+    if (typeof chunk === "string")
+        return chunk;
+    if (typeof chunk.text === "string")
+        return chunk.text;
+    if (typeof chunk.content === "string")
+        return chunk.content;
+    return "";
+};
+const emitNodeEvent = (emitEvent, nodeId, event, payload) => {
+    if (!emitEvent)
+        return;
+    emitEvent(event, {
+        ...payload,
+        ...(typeof nodeId === "string" && nodeId.length > 0
+            ? { node: nodeId }
+            : {}),
+    });
+};
+async function runReasonEngine(args) {
+    const stream = args.stream ?? args.model.options?.streaming ?? true;
+    const emit = args.emit ?? true;
+    const temperature = args.temperature ??
+        args.model.options?.temperature ??
+        args.defaultTemperature;
+    const model = args.getProvider(args.model.providerId, args.model.modelId, {
+        ...(temperature !== undefined ? { temperature } : {}),
+        streaming: stream,
+    });
+    const messages = [];
+    if (typeof args.system === "string" && args.system.length > 0) {
+        messages.push({ role: "system", content: args.system });
+    }
+    messages.push({ role: "user", content: String(args.input ?? "") });
+    if (stream) {
+        let final = "";
+        let raw;
+        if (emit) {
+            emitNodeEvent(args.emitEvent, args.nodeId, "text-start", {});
+        }
+        const response = await model.stream(messages);
+        for await (const chunk of response) {
+            const text = chunkToText(chunk);
+            if (!text)
+                continue;
+            final += text;
+            if (typeof chunk === "object" && chunk && "raw" in chunk) {
+                raw = chunk.raw;
+            }
+            if (emit) {
+                emitNodeEvent(args.emitEvent, args.nodeId, "text-delta", {
+                    delta: text,
+                });
+            }
+        }
+        if (emit) {
+            emitNodeEvent(args.emitEvent, args.nodeId, "text-end", {});
+        }
+        return {
+            text: final,
+            ...(raw !== undefined ? { raw } : {}),
+        };
+    }
+    const response = await model.invoke(messages);
+    if (emit) {
+        emitNodeEvent(args.emitEvent, args.nodeId, "text-start", {});
+        if (response.content) {
+            emitNodeEvent(args.emitEvent, args.nodeId, "text-delta", {
+                delta: response.content,
+            });
+        }
+        emitNodeEvent(args.emitEvent, args.nodeId, "text-end", {});
+    }
+    return {
+        text: response.content,
+        ...(response.raw !== undefined ? { raw: response.raw } : {}),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kortyx/hooks",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "description": "Lifecycle hooks and extension points for Kortyx.",
   "keywords": [
@@ -24,6 +24,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
     }
   },
   "files": [