@kortyx/hooks 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.5.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.4.1...hooks-v0.5.0) (2026-02-17)
+
+
+### Features
+
+* **hooks:** consolidate reason+interrupt contracts ([4716a4d](https://github.com/kortyx-io/kortyx/commit/4716a4d4739b4a71b7c6e84717c830cd9ff625a6))
+
+
+### Bug Fixes
+
+* **hooks:** stabilize useReason interrupt resume and split internals ([fa24712](https://github.com/kortyx-io/kortyx/commit/fa247129f160d129cdf2c05f0a48a2236ea71bb8))
+* **testing:** add hooks vitest suite and enforce CI test gates ([d3ecdcb](https://github.com/kortyx-io/kortyx/commit/d3ecdcbd0c9e48d88231f0a75eb3b3b2339e9d6d))
+
+## [0.4.1](https://github.com/kortyx-io/kortyx/compare/hooks-v0.4.0...hooks-v0.4.1) (2026-02-17)
+
+
+### Bug Fixes
+
+* **build:** align package tsconfig with shared lib baseline ([48d2b57](https://github.com/kortyx-io/kortyx/commit/48d2b5765fefbb5fcbbe548e749e7b5f51b450b9))
+* **build:** wire tsup for publishable packages ([e7b1b5c](https://github.com/kortyx-io/kortyx/commit/e7b1b5c28af55becffc137233dd92d8953d7cb8e))
+* **dev:** restore tsc watch flow for local workspace ([4305823](https://github.com/kortyx-io/kortyx/commit/430582372cad466bf28af554042aa11bdb8bf027))
+
 ## [0.4.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.3.0...hooks-v0.4.0) (2026-02-17)
 
 

package/README.md

@@ -8,13 +8,30 @@ Lifecycle hooks and extension points for Kortyx.
 npm install @kortyx/hooks
 ```
 
-## Documentation
+## Key APIs
+
+- `useReason(...)` for model calls, optional schema-constrained interrupt flow, and structured output.
+- `useInterrupt(...)` for explicit human-in-the-loop pauses.
+- `useStructuredData(...)` for UI-friendly structured stream events.
+- `useNodeState(...)` / `useWorkflowState(...)` for stateful node logic.
+
+## LangGraph Resume Behavior
+
+Kortyx uses LangGraph as the execution engine. On resume, the node function is replayed from the top.
+
+- `useReason` resumes from its internal checkpoint.
+- Code before `useReason` will re-run unless guarded.
 
-This repo is under active development. For the latest package list and links, see the monorepo README:
+Workarounds:
 
-- `README.md`
+- Keep nodes minimal and call `useReason` first.
+- Guard pre-`useReason` side effects with `useNodeState`.
+
+## Documentation
+
+- Runtime hooks: `apps/website/src/docs/v0/03-runtime/01-hooks.md`
+- Interrupts/resume: `apps/website/src/docs/v0/03-runtime/02-interrupts-and-resume.md`
 
 ## License
 
 Apache-2.0
-

package/dist/index.d.ts

@@ -1,5 +1,92 @@
-export type { HookRuntimeContext } from "./context";
-export { runWithHookContext } from "./context";
-export type { UseReasonArgs, UseReasonResult } from "./hooks";
-export { useAiInterrupt, useAiMemory, useEmit, useNodeState, useReason, useStructuredData, useWorkflowState, } from "./hooks";
-//# sourceMappingURL=index.d.ts.map
+import { NodeContext, GraphState, InterruptInput, InterruptResult } from '@kortyx/core';
+import { MemoryAdapter } from '@kortyx/memory';
+import { GetProviderFn, ProviderModelRef } from '@kortyx/providers';
+
+type HookRuntimeContext = {
+    node: NodeContext;
+    state: GraphState;
+    getProvider?: GetProviderFn;
+    memoryAdapter?: MemoryAdapter;
+};
+declare function runWithHookContext<T>(ctx: HookRuntimeContext, fn: () => Promise<T>): Promise<{
+    result: T;
+    memoryUpdates: Record<string, unknown> | null;
+}>;
+
+type SchemaLike<T> = {
+    safeParse: (value: unknown) => {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            message?: string;
+        };
+    };
+};
+type StructuredDataMode = "final" | "patch" | "snapshot";
+type UseStructuredDataArgs<TData = unknown> = {
+    data: TData;
+    dataType?: string | undefined;
+    dataSchema?: SchemaLike<TData> | undefined;
+    mode?: StructuredDataMode | undefined;
+    schemaId?: string | undefined;
+    schemaVersion?: string | undefined;
+    id?: string | undefined;
+    opId?: string | undefined;
+};
+type UseReasonStructuredStreamMode = "off" | "patch" | "snapshot";
+type UseReasonStructuredConfig = {
+    stream?: UseReasonStructuredStreamMode | undefined;
+    optimistic?: boolean | undefined;
+    dataType?: string | undefined;
+    schemaId?: string | undefined;
+    schemaVersion?: string | undefined;
+};
+type UseReasonInterruptConfig<TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult> = {
+    requestSchema: SchemaLike<TRequest>;
+    responseSchema?: SchemaLike<TResponse> | undefined;
+    schemaId?: string | undefined;
+    schemaVersion?: string | undefined;
+};
+type UseReasonArgs<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult> = {
+    model: ProviderModelRef;
+    input: string;
+    system?: string | undefined;
+    temperature?: number | undefined;
+    emit?: boolean | undefined;
+    stream?: boolean | undefined;
+    id?: string | undefined;
+    outputSchema?: SchemaLike<TOutput> | undefined;
+    structured?: UseReasonStructuredConfig | undefined;
+    interrupt?: UseReasonInterruptConfig<TRequest, TResponse> | undefined;
+};
+type UseReasonResult<TOutput = unknown, TResponse = InterruptResult> = {
+    id?: string;
+    opId: string;
+    text: string;
+    raw?: unknown;
+    output?: TOutput;
+    interruptResponse?: TResponse;
+};
+type UseInterruptArgs<TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult> = {
+    request: TRequest;
+    requestSchema?: SchemaLike<TRequest> | undefined;
+    responseSchema?: SchemaLike<TResponse> | undefined;
+    schemaId?: string | undefined;
+    schemaVersion?: string | undefined;
+    id?: string | undefined;
+    meta?: Record<string, unknown> | undefined;
+};
+
+type StateSetter<T> = (next: T | ((prev: T) => T)) => void;
+declare function useEmit(): NodeContext["emit"];
+declare function useStructuredData<TData = unknown>(args: UseStructuredDataArgs<TData>): void;
+declare function useReason<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult>(args: UseReasonArgs<TOutput, TRequest, TResponse>): Promise<UseReasonResult<TOutput, TResponse>>;
+declare function useAiMemory(): MemoryAdapter;
+declare function useInterrupt<TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult>(args: UseInterruptArgs<TRequest, TResponse>): Promise<TResponse>;
+declare function useNodeState<T>(initialValue: T): [T, StateSetter<T>];
+declare function useNodeState<T>(key: string, initialValue?: T): [T, StateSetter<T>];
+declare function useWorkflowState<T>(key: string, initialValue?: T): [T, StateSetter<T>];
+
+export { type HookRuntimeContext, type UseInterruptArgs, type UseReasonArgs, type UseReasonResult, type UseStructuredDataArgs, runWithHookContext, useAiMemory, useEmit, useInterrupt, useNodeState, useReason, useStructuredData, useWorkflowState };