@kortyx/hooks 0.28.1 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.30.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.29.0...hooks-v0.30.0) (2026-09-30)
+
+
+### Features
+
+* **hooks:** add realtime model-selected output contracts ([#249](https://github.com/kortyx-io/kortyx/issues/249)) ([ac52b47](https://github.com/kortyx-io/kortyx/commit/ac52b47151b64ce5be6ce6c7fd42d34a0fa8a76d))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/telemetry-contracts bumped to 0.12.0
+
+## [0.29.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.28.1...hooks-v0.29.0) (2026-09-22)
+
+
+### Features
+
+* **providers:** add OpenRouter and Jev support ([#230](https://github.com/kortyx-io/kortyx/issues/230)) ([7a6ac2c](https://github.com/kortyx-io/kortyx/commit/7a6ac2c2171850fa89f041e66c980521409e6819))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/core bumped to 0.11.0
+    * @kortyx/providers bumped to 0.8.3
+
 ## [0.28.1](https://github.com/kortyx-io/kortyx/compare/hooks-v0.28.0...hooks-v0.28.1) (2026-09-21)
 
 

package/README.md

@@ -24,6 +24,7 @@ npm install @kortyx/hooks
 - `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.
+- `defineOutputContract(...)` for reusable model-selected and application-authored structured values.
 - `useRuntimeContext(...)` for request context made available to node execution.
 - `useNodeState(...)` / `useWorkflowState(...)` for stateful node logic.
 
@@ -38,6 +39,16 @@ The singular `useReason({ interrupt })` option and `result.interruptResponse`
 are deprecated and will be removed in the next major release. Migrate to
 `interrupts.contracts` and `result.interruptHistory`.
 
+Pass output contracts through `useReason({ outputs: { emit, return } })` to let
+the model emit values between text segments or choose a typed terminal result.
+Contracts with `stream.fields` start a separate streamed JSON pass and publish
+partial `set`, `append`, or `text-delta` updates before the validated `final`
+value. `useStructuredData({ contract, data })` uses the same stream contract for
+application-authored values. The older `outputSchema` and `structured` options
+and `result.output` remain available during migration, but are deprecated and
+scheduled for removal in the next major release. TypeSafe Jev's provider-native
+decision schema is a temporary exception until a non-tool replacement ships.
+
 ## Runtime Resume Behavior
 
 On resume, the node function is replayed from the top.

package/dist/index.d.ts

@@ -110,6 +110,10 @@ declare function runWithHookContext<T>(ctx: HookRuntimeContext, fn: () => Promis
 }>;
 
 type SchemaLike<T> = {
+    /** Provider helpers can opt out of prompt-appended output instructions. */
+    readonly "~kortyx"?: {
+        readonly nativeOutput?: boolean | undefined;
+    } | undefined;
     safeParse: (value: unknown) => {
         success: true;
         data: T;
@@ -131,6 +135,28 @@ type InterruptContract<TRequest = unknown, TResponse = unknown> = {
     schemaVersion: string;
 };
 type InterruptContractMap = Record<string, InterruptContract<unknown, unknown>>;
+type OutputContract<TData = unknown> = {
+    description: string;
+    schema: SchemaLike<TData>;
+    schemaId: string;
+    schemaVersion: string;
+    /** Paths the model may update before emitting the validated final value. */
+    stream?: {
+        fields: UseReasonStructuredFields;
+    } | undefined;
+};
+type OutputContractMap = Record<string, OutputContract<unknown>>;
+type UseReasonOutputsConfig<TEmit extends OutputContractMap = OutputContractMap, TReturn extends OutputContractMap = OutputContractMap> = {
+    emit?: TEmit | undefined;
+    return?: TReturn | undefined;
+    maxEmissions?: number | undefined;
+};
+type OutputContractEntry<TContracts extends OutputContractMap> = {
+    [TName in Extract<keyof TContracts, string>]: TContracts[TName] extends OutputContract<infer TData> ? {
+        contract: TName;
+        data: TData;
+    } : never;
+}[Extract<keyof TContracts, string>];
 type UseReasonInterruptsConfig<TContracts extends InterruptContractMap = InterruptContractMap> = {
     mode?: "required" | "optional" | undefined;
     /** Maximum number of model-requested human interactions for this operation. */
@@ -155,6 +181,31 @@ type UseStructuredDataBaseArgs = {
     id?: string | undefined;
     streamId?: string | undefined;
 };
+type UseContractStructuredDataArgs<TData> = {
+    contract: OutputContract<TData>;
+    id?: string | undefined;
+} & ({
+    kind?: "final" | undefined;
+    data: TData;
+    streamId?: string | undefined;
+} | {
+    kind: "set";
+    path: string;
+    value: unknown;
+    valueSchema?: SchemaLike<unknown> | undefined;
+    streamId: string;
+} | {
+    kind: "append";
+    path: string;
+    items: unknown[];
+    itemSchema?: SchemaLike<unknown> | undefined;
+    streamId: string;
+} | {
+    kind: "text-delta";
+    path: string;
+    delta: string;
+    streamId: string;
+});
 type UseStructuredDataFinalArgs<TData = unknown> = UseStructuredDataBaseArgs & {
     kind?: "final" | undefined;
     data: TData;
@@ -211,7 +262,7 @@ type UseReasonToolExecution = {
     approval?: boolean | Record<string, boolean> | undefined;
     emit?: boolean | Record<string, boolean> | undefined;
 };
-type UseReasonArgs<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult, TContracts extends InterruptContractMap = InterruptContractMap> = {
+type UseReasonArgs<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult, TContracts extends InterruptContractMap = InterruptContractMap, TEmit extends OutputContractMap = OutputContractMap, TReturn extends OutputContractMap = OutputContractMap> = {
     model: ProviderModelRef;
     input: string;
     system?: string | undefined;
@@ -226,8 +277,11 @@ type UseReasonArgs<TOutput = unknown, TRequest extends InterruptInput = Interrup
     stream?: boolean | undefined;
     id?: string | undefined;
     telemetry?: KortyxTraceMetadata | undefined;
+    /** @deprecated Removed in the next major. Use `outputs.return` with `defineOutputContract`. */
     outputSchema?: SchemaLike<TOutput> | undefined;
+    /** @deprecated Removed in the next major. Use output contracts for model-selected structured emissions. */
     structured?: UseReasonStructuredConfig | undefined;
+    outputs?: UseReasonOutputsConfig<TEmit, TReturn> | undefined;
     /** @deprecated Use `interrupts`. Removed in the next major release. */
     interrupt?: UseReasonInterruptConfig<TRequest, TResponse> | undefined;
     interrupts?: UseReasonInterruptsConfig<TContracts> | undefined;
@@ -235,6 +289,7 @@ type UseReasonArgs<TOutput = unknown, TRequest extends InterruptInput = Interrup
     toolExecution?: UseReasonToolExecution | undefined;
 };
 type UseReasonStep = {
+    kind?: "output" | undefined;
     toolObservations?: _kortyx_providers.ToolObservation[];
     stepIndex: number;
     text: string;
@@ -245,7 +300,7 @@ type UseReasonStep = {
     providerMetadata?: KortyxProviderMetadata | undefined;
     warnings?: KortyxWarning[] | undefined;
 };
-type UseReasonResult<TOutput = unknown, TResponse = InterruptResult, TContracts extends InterruptContractMap = InterruptContractMap> = {
+type UseReasonResult<TOutput = unknown, TResponse = InterruptResult, TContracts extends InterruptContractMap = InterruptContractMap, TEmit extends OutputContractMap = OutputContractMap, TReturn extends OutputContractMap = OutputContractMap> = {
     id?: string;
     opId: string;
     text: string;
@@ -254,7 +309,10 @@ type UseReasonResult<TOutput = unknown, TResponse = InterruptResult, TContracts
     finishReason?: KortyxFinishReason;
     providerMetadata?: KortyxProviderMetadata;
     warnings?: KortyxWarning[];
+    /** @deprecated Removed in the next major. Use `returned` from an output contract. */
     output?: TOutput;
+    emissions?: OutputContractEntry<TEmit>[];
+    returned?: OutputContractEntry<TReturn>;
     /** @deprecated Use `interruptHistory`. Removed in the next major release. */
     interruptResponse?: TResponse;
     interruptHistory?: InterruptHistoryEntry<TContracts>[];
@@ -280,9 +338,12 @@ type UseContractInterruptArgs<TRequest, TResponse> = {
 
 declare const defineInterruptContract: <TRequest, TResponse>(contract: InterruptContract<TRequest, TResponse>) => InterruptContract<TRequest, TResponse>;
 
+declare const defineOutputContract: <TData>(contract: OutputContract<TData>) => OutputContract<TData>;
+
 type StateSetter<T> = (next: T | ((prev: T) => T)) => void;
+declare function useStructuredData<TData>(args: UseContractStructuredDataArgs<TData>): void;
 declare function useStructuredData<TData = unknown>(args: UseStructuredDataArgs<TData>): void;
-declare function useReason<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult, TContracts extends InterruptContractMap = InterruptContractMap>(args: UseReasonArgs<TOutput, TRequest, TResponse, TContracts>): Promise<UseReasonResult<TOutput, TResponse, TContracts>>;
+declare function useReason<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult, TContracts extends InterruptContractMap = InterruptContractMap, TEmit extends OutputContractMap = OutputContractMap, TReturn extends OutputContractMap = OutputContractMap>(args: UseReasonArgs<TOutput, TRequest, TResponse, TContracts, TEmit, TReturn>): Promise<UseReasonResult<TOutput, TResponse, TContracts, TEmit, TReturn>>;
 declare function useInterrupt<TRequest, TResponse>(args: UseContractInterruptArgs<TRequest, TResponse>): Promise<TResponse>;
 declare function useInterrupt<TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult>(args: UseInterruptArgs<TRequest, TResponse>): Promise<TResponse>;
 /** Live execution signal for cooperative I/O. Never store it in workflow state. */
@@ -305,4 +366,4 @@ declare function useTool<T extends KortyxExecutableTool>(args: UseToolArgs<T>):
 /** Best effort lifecycle facts. Engine snapshots and interrupt tokens never leave the runtime. */
 declare function emitWorkflowCall(telemetry: KortyxTelemetryConfig | undefined, type: KortyxTelemetryEventType, payload: Record<string, unknown>): void;
 
-export { type CompleteResponseOptions, type HookRuntimeContext, type InterruptContract, type InterruptContractMap, type InterruptHistoryEntry, KortyxTelemetryConfig, KortyxTelemetryEventType, KortyxTraceMetadata, ParallelError, ReasonTraceAdapter, ReportErrorOptions, type UseContractInterruptArgs, type UseInterruptArgs, type UseReasonArgs, type UseReasonInterruptConfig, type UseReasonInterruptsConfig, type UseReasonResult, type UseReasonStep, type UseReasonToolExecution, type UseStructuredDataArgs, type UseToolArgs, WorkflowCallError, type WorkflowCallOutcome, type WorkflowCallService, completeResponse, createWorkflowHooks, defineInterruptContract, emitWorkflowCall, parallel, reportError, runWithHookContext, useAbortSignal, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useTool, useWorkflow, useWorkflowState, workflowCallFingerprint };
+export { type CompleteResponseOptions, type HookRuntimeContext, type InterruptContract, type InterruptContractMap, type InterruptHistoryEntry, KortyxTelemetryConfig, KortyxTelemetryEventType, KortyxTraceMetadata, type OutputContract, type OutputContractEntry, type OutputContractMap, ParallelError, ReasonTraceAdapter, ReportErrorOptions, type UseContractInterruptArgs, type UseContractStructuredDataArgs, type UseInterruptArgs, type UseReasonArgs, type UseReasonInterruptConfig, type UseReasonInterruptsConfig, type UseReasonOutputsConfig, type UseReasonResult, type UseReasonStep, type UseReasonToolExecution, type UseStructuredDataArgs, type UseToolArgs, WorkflowCallError, type WorkflowCallOutcome, type WorkflowCallService, completeResponse, createWorkflowHooks, defineInterruptContract, defineOutputContract, emitWorkflowCall, parallel, reportError, runWithHookContext, useAbortSignal, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useTool, useWorkflow, useWorkflowState, workflowCallFingerprint };