@kortyx/hooks 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## [0.34.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.33.0...hooks-v0.34.0) (2026-10-11)
+
+
+### Features
+
+* add shared SDK and Studio usage telemetry ([#313](https://github.com/kortyx-io/kortyx/issues/313)) ([7d5f0c0](https://github.com/kortyx-io/kortyx/commit/7d5f0c005bd7721dc6a529554e75c14573d76a0f))
+
+
+### Bug Fixes
+
+* **website:** reconcile credibility branch with current main ([60199f9](https://github.com/kortyx-io/kortyx/commit/60199f992242eb7c409a95bc7a6898d31bac601d))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/core bumped to 0.13.1
+    * @kortyx/providers bumped to 0.9.2
+    * @kortyx/telemetry-contracts bumped to 0.17.0
+    * @kortyx/prompts bumped to 0.2.0
+    * @kortyx/usage-telemetry bumped to 0.2.0
+
+## [0.33.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.32.1...hooks-v0.33.0) (2026-10-10)
+
+
+### Features
+
+* version, evaluate, serve and migrate Studio prompts ([#288](https://github.com/kortyx-io/kortyx/issues/288)) ([0802f8b](https://github.com/kortyx-io/kortyx/commit/0802f8b91c4a541d176dd8a75c659063e2c28c8c))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/telemetry-contracts bumped to 0.16.0
+    * @kortyx/prompts bumped to 0.1.0
+
+## [0.32.1](https://github.com/kortyx-io/kortyx/compare/hooks-v0.32.0...hooks-v0.32.1) (2026-10-09)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/core bumped to 0.13.0
+    * @kortyx/providers bumped to 0.9.1
+
 ## [0.32.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.31.0...hooks-v0.32.0) (2026-10-08)
 
 

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import * as _kortyx_core from '@kortyx/core';
 import { WorkflowDefinition, TokenUsage, InterruptInput, GraphState, NodeConfig, InterruptResumeValue, InterruptResult } from '@kortyx/core';
+import * as _kortyx_prompts from '@kortyx/prompts';
+import { CompiledPrompt, PromptRef } from '@kortyx/prompts';
 import { K as KortyxTelemetryConfig, R as ReasonTraceAdapter, a as KortyxTraceMetadata, b as ReportErrorOptions, c as KortyxTelemetryEventType } from './tracing-mXE0Euvx.js';
 export { E as EnsureWorkflowTopologyRequest, d as EnsureWorkflowTopologyResponse, e as KortyxErrorDetails, f as KortyxTelemetryContentCapture, g as KortyxTelemetryCorrelation, h as KortyxTelemetryEvent, i as KortyxTelemetryPrompt, j as KortyxTelemetryReporter, k as KortyxTelemetryService, l as KortyxTraceAdapter, m as KortyxTraceErrorProjection, n as ReasonTraceAttributes, o as ReasonTraceSpan, p as ReasonTraceSpanEndArgs, q as ReasonTraceSpanStartArgs } from './tracing-mXE0Euvx.js';
 import { FailureDescriptor, KortyxError } from '@kortyx/core/errors';
@@ -12,7 +14,6 @@ type CompleteResponseOptions = {
     message?: string | undefined;
     data?: unknown;
 };
-/** Finish client delivery, leaving the node and workflow execution running. */
 declare function completeResponse(options?: CompleteResponseOptions): Promise<void>;
 
 /** All siblings have settled; results retain the order passed to parallel(). */
@@ -85,6 +86,7 @@ declare function useWorkflow(args: {
 }>;
 
 type HookNodeRuntimeContext = {
+    prompts?: _kortyx_prompts.PromptExecution | undefined;
     completeResponse?: ((options: CompleteResponseOptions, state: GraphState) => Promise<void>) | undefined;
     /** Transient execution control; never part of checkpointed state. */
     abortSignal?: AbortSignal | undefined;
@@ -267,6 +269,7 @@ type UseReasonToolExecution = {
 };
 type UseReasonArgs<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult, TContracts extends InterruptContractMap = InterruptContractMap, TEmit extends OutputContractMap = OutputContractMap, TReturn extends OutputContractMap = OutputContractMap> = {
     model: ProviderModelRef;
+    messages?: _kortyx_providers.KortyxPromptMessage[] | undefined;
     input: string;
     system?: string | undefined;
     temperature?: number | undefined;
@@ -346,7 +349,12 @@ declare const defineOutputContract: <TData>(contract: 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, 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 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> | (Omit<UseReasonArgs<TOutput, TRequest, TResponse, TContracts, TEmit, TReturn>, "input" | "system" | "messages"> & {
+    prompt: CompiledPrompt;
+    input?: never;
+    system?: never;
+    messages?: never;
+})): 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. */
@@ -355,6 +363,12 @@ declare function useRuntimeContext<TContext extends Record<string, unknown> = Re
 declare function useNodeState<T>(initialValue: T): [T, StateSetter<T>];
 declare function useWorkflowState<T>(key: string, ...rest: [] | [T]): [T, StateSetter<T>];
 
+type UseReasonPromptArgs = Omit<UseReasonArgs, "input" | "system" | "messages"> & {
+    prompt: CompiledPrompt;
+    input?: never;
+    system?: never;
+};
+
 /** Reports a handled error to the configured observer without stopping execution. */
 declare function reportError(error: unknown, options?: ReportErrorOptions): void;
 
@@ -366,7 +380,13 @@ type UseToolArgs<T extends KortyxExecutableTool> = {
 };
 declare function useTool<T extends KortyxExecutableTool>(args: UseToolArgs<T>): Promise<Awaited<ReturnType<T["execute"]>>>;
 
+/** Resolve both roles from one immutable version in the current execution. */
+declare function usePrompt<Inputs, Config>(reference: PromptRef<Inputs, Config>, options: {
+    variables: Inputs;
+    version?: number;
+}): Promise<CompiledPrompt<Config>>;
+
 /** 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, 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 };
+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 UseReasonPromptArgs, 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, usePrompt, useReason, useRuntimeContext, useStructuredData, useTool, useWorkflow, useWorkflowState, workflowCallFingerprint };

package/dist/index.js

@@ -32,6 +32,7 @@ __export(index_exports, {
   useAbortSignal: () => useAbortSignal,
   useInterrupt: () => useInterrupt,
   useNodeState: () => useNodeState,
+  usePrompt: () => usePrompt,
   useReason: () => useReason2,
   useRuntimeContext: () => useRuntimeContext,
   useStructuredData: () => useStructuredData,
@@ -137,11 +138,11 @@ var cleanupCompletedReasonCheckpoints = (ctx) => {
   }
   if (changed) ctx.stateDirty = true;
 };
-var toTokenUsageDelta = (usage) => {
-  if (!usage) return void 0;
-  const input = usage.input ?? 0;
-  const output = usage.output ?? 0;
-  const total = usage.total ?? input + output + (usage.outputIncludesReasoning ? 0 : usage.reasoning ?? 0);
+var toTokenUsageDelta = (usage2) => {
+  if (!usage2) return void 0;
+  const input = usage2.input ?? 0;
+  const output = usage2.output ?? 0;
+  const total = usage2.total ?? input + output + (usage2.outputIncludesReasoning ? 0 : usage2.reasoning ?? 0);
   if (input === 0 && output === 0 && total === 0) {
     return void 0;
   }
@@ -151,8 +152,8 @@ var toTokenUsageDelta = (usage) => {
     total
   };
 };
-function accumulateTokenUsage(usage) {
-  const delta = toTokenUsageDelta(usage);
+function accumulateTokenUsage(usage2) {
+  const delta = toTokenUsageDelta(usage2);
   if (!delta) return;
   const ctx = getHookContext();
   const current = ctx.tokenUsage ?? {
@@ -238,12 +239,98 @@ function snapshotHookState() {
   };
 }
 
+// src/usage.ts
+var import_node = require("@kortyx/usage-telemetry/node");
+
+// package.json
+var package_default = {
+  name: "@kortyx/hooks",
+  version: "0.34.0",
+  private: false,
+  description: "Lifecycle hooks and extension points for Kortyx.",
+  keywords: [
+    "ai",
+    "agent",
+    "agents",
+    "orchestration",
+    "framework",
+    "hooks",
+    "kortyx"
+  ],
+  license: "Apache-2.0",
+  homepage: "https://kortyx.io/",
+  bugs: {
+    url: "https://github.com/kortyx-io/kortyx/issues"
+  },
+  author: "Kortyx (https://github.com/kortyx-io)",
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      default: "./dist/index.js"
+    },
+    "./internal": {
+      types: "./dist/internal.d.ts",
+      default: "./dist/internal.js"
+    }
+  },
+  files: [
+    "dist/**",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  scripts: {
+    build: "tsup",
+    predev: "tsc -p tsconfig.build.json",
+    dev: "tsc --watch",
+    lint: "biome check src",
+    test: "vitest run && pnpm -s type-check",
+    coverage: "vitest run --coverage && pnpm -s type-check",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit -p tsconfig.test.json"
+  },
+  dependencies: {
+    "@kortyx/core": "workspace:*",
+    "@kortyx/providers": "workspace:*",
+    "@kortyx/telemetry-contracts": "workspace:*",
+    zod: "catalog:",
+    "@kortyx/prompts": "workspace:*",
+    "@kortyx/usage-telemetry": "workspace:*"
+  },
+  devDependencies: {
+    turbo: "catalog:",
+    typescript: "catalog:",
+    tsup: "catalog:",
+    vitest: "catalog:",
+    "@vitest/coverage-v8": "catalog:"
+  },
+  sideEffects: false,
+  repository: {
+    type: "git",
+    url: "https://github.com/kortyx-io/kortyx.git",
+    directory: "packages/hooks"
+  },
+  publishConfig: {
+    access: "public"
+  }
+};
+
+// src/usage.ts
+var client = () => (0, import_node.getUsageTelemetry)("hooks", package_default.version);
+var usage = {
+  start: (...args) => client().start(...args),
+  feature: (...args) => client().feature(...args),
+  measure: (...args) => client().measure(...args),
+  flush: () => client().flush()
+};
+
 // src/complete-response.ts
 var optionsSchema = import_zod.z.object({
   message: import_zod.z.string().optional(),
   data: import_zod.z.json().optional()
 }).strict();
-async function completeResponse(options = {}) {
+async function completeResponseInternal(options = {}) {
   const ctx = getHookContext();
   const parsed = optionsSchema.parse(options);
   if (!ctx.node.completeResponse) {
@@ -253,6 +340,12 @@ async function completeResponse(options = {}) {
   }
   await ctx.node.completeResponse(parsed, snapshotHookState());
 }
+function completeResponse(options = {}) {
+  return usage.measure(
+    "sdk.complete_response",
+    () => completeResponseInternal(options)
+  );
+}
 
 // src/interrupt.ts
 var import_core = require("@kortyx/core");
@@ -651,7 +744,7 @@ var createStructuredStreamId = () => {
     return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
   }
 };
-var emitStructuredData = (args) => {
+var emitStructuredDataInternal = (args) => {
   const ctx = getHookContext();
   const streamId = typeof args.streamId === "string" && args.streamId.length > 0 ? args.streamId : createStructuredStreamId();
   const dataType = typeof args.dataType === "string" && args.dataType.length > 0 ? args.dataType : "generic";
@@ -714,6 +807,16 @@ var emitStructuredData = (args) => {
 };
 var shouldEmitStructured = (cfg) => Boolean(cfg);
 var shouldStreamStructured = (cfg) => Boolean(cfg) && (cfg?.stream ?? true);
+var emitStructuredData = (args) => {
+  const scope = usage.start("sdk.structured", { format: args.kind });
+  try {
+    emitStructuredDataInternal(args);
+    scope.end();
+  } catch (error) {
+    scope.fail(error);
+    throw error;
+  }
+};
 
 // src/tool.ts
 var import_node_async_hooks2 = require("async_hooks");
@@ -1191,6 +1294,11 @@ async function executeObservedTool(args) {
   }
   ctx.node.consumeExecution?.("maxToolCalls");
   observation.executed = true;
+  const operationUsage = usage.start("sdk.tool", {
+    calling_mode: args.callingMode,
+    source: args.tool.source === "mcp" ? "mcp" : "native",
+    executed: true
+  });
   const started = performance.now();
   return withSafeTraceSpan(
     toolTrace(observation),
@@ -1240,9 +1348,13 @@ async function executeObservedTool(args) {
               scope.telemetry ?? args.tool.telemetry
             );
         }
+        if (observation.outcome === "fault") operationUsage.fail(error);
         throw error;
       } finally {
         observation.durationMs = Math.max(0, performance.now() - started);
+        operationUsage.end(
+          observation.outcome === "fault" ? "failed" : observation.outcome ?? "suspended"
+        );
         span.end?.({
           attributes: {
             ...observation,
@@ -1354,6 +1466,7 @@ var ownershipFrom = (observation) => ({
 // src/reason/engine.ts
 var import_node_crypto5 = require("crypto");
 var import_core4 = require("@kortyx/core");
+var import_prompts = require("@kortyx/prompts");
 
 // src/reason-engine.ts
 var import_node_crypto4 = require("crypto");
@@ -1398,7 +1511,7 @@ var resolveProviderOptions = (defaults, overrides) => {
   }
   return providerOptions;
 };
-async function runReasonEngine(args) {
+async function runReasonEngineInternal(args) {
   let stream = args.stream ?? args.model.options?.streaming ?? true;
   const emit = args.emit ?? true;
   const temperature = args.temperature ?? args.model.options?.temperature ?? args.defaultTemperature;
@@ -1425,6 +1538,11 @@ async function runReasonEngine(args) {
     ...providerOptions !== void 0 ? { providerOptions } : {}
   });
   if (tools2?.length && !model.supportsToolStreaming) stream = false;
+  usage.feature("sdk.model", {
+    streaming: stream,
+    tools: Boolean(tools2?.length),
+    provider: args.model.provider.id
+  });
   const messages = args.messages !== void 0 ? args.messages : [
     ...typeof args.system === "string" && args.system.length > 0 ? [{ role: "system", content: args.system }] : [],
     { role: "user", content: String(args.input ?? "") }
@@ -1504,7 +1622,7 @@ async function runReasonEngine(args) {
       let continuation;
       let final = "";
       let raw;
-      let usage;
+      let usage2;
       let finishReason;
       let toolCalls;
       let providerMetadata;
@@ -1545,7 +1663,7 @@ async function runReasonEngine(args) {
               raw = chunk.raw;
             }
             if (chunk.usage !== void 0) {
-              usage = chunk.usage;
+              usage2 = chunk.usage;
             }
             if (chunk.finishReason !== void 0) {
               finishReason = chunk.finishReason;
@@ -1583,7 +1701,7 @@ async function runReasonEngine(args) {
         }
       }
       (0, import_core3.throwIfExecutionAborted)(abortSignal);
-      assertModelFinish({ finishReason, usage });
+      assertModelFinish({ finishReason, usage: usage2 });
       if (emit) {
         emitNodeEvent(args.emitEvent, args.nodeId, "text-end", {
           ...commonMeta
@@ -1593,7 +1711,7 @@ async function runReasonEngine(args) {
         text: final,
         ...continuation ? { continuation } : {},
         ...raw !== void 0 ? { raw } : {},
-        ...usage !== void 0 ? { usage } : {},
+        ...usage2 !== void 0 ? { usage: usage2 } : {},
         ...finishReason !== void 0 ? { finishReason } : {},
         ...toolCalls !== void 0 ? { toolCalls } : {},
         ...providerMetadata !== void 0 ? { providerMetadata } : {},
@@ -1639,6 +1757,14 @@ async function runReasonEngine(args) {
     throw failure;
   }
 }
+function runReasonEngine(args) {
+  return usage.measure("sdk.model", () => runReasonEngineInternal(args), {
+    provider: args.model.provider.id,
+    requested_streaming: args.stream ?? args.model.options?.streaming ?? true,
+    tools: Boolean((args.tools ?? args.model.options?.tools)?.length),
+    format: args.responseFormat?.type ?? args.model.options?.responseFormat?.type ?? "text"
+  });
+}
 
 // src/reason/engine.ts
 var createRuntimeId2 = () => {
@@ -1657,6 +1783,19 @@ async function reasonEngine(args, meta, inputOverride) {
   );
   (0, import_core4.throwIfExecutionAborted)(abortSignal);
   ctx.node.consumeExecution?.("maxModelPasses");
+  const prompt = args.telemetry?.prompt;
+  const identity = prompt?.metadata;
+  if ((0, import_prompts.isPromptUsageMetadata)(identity)) {
+    const { dependencies, ...parent } = identity;
+    ctx.node.prompts?.recordUsage({ ...parent, model: args.model.modelId });
+    for (const dependency of dependencies ?? [])
+      ctx.node.prompts?.recordUsage({
+        ...dependency,
+        environment: identity.environment,
+        snapshotRevision: identity.snapshotRevision,
+        model: args.model.modelId
+      });
+  }
   try {
     return await runReasonEngine({
       model: args.model,
@@ -1670,7 +1809,12 @@ async function reasonEngine(args, meta, inputOverride) {
       responseFormat: args.responseFormat,
       providerOptions: args.providerOptions,
       tools: args.tools,
-      messages: args.messages,
+      messages: args.messages && inputOverride !== void 0 ? args.messages.map(
+        (message, index) => index === args.messages.reduce(
+          (last, item, position) => item.role === "user" ? position : last,
+          -1
+        ) ? { ...message, content: inputOverride } : message
+      ) : args.messages,
       defaultTemperature: ctx.node.config?.model?.temperature,
       stream: args.stream,
       emit: args.emit,
@@ -1683,8 +1827,8 @@ async function reasonEngine(args, meta, inputOverride) {
       opId: meta.opId
     });
   } catch (error) {
-    const usage = error?.usage;
-    if (usage) accumulateTokenUsage(usage);
+    const usage2 = error?.usage;
+    if (usage2) accumulateTokenUsage(usage2);
     throw error;
   }
 }
@@ -2574,6 +2718,38 @@ var parseInterruptFirstPassResult = (args) => {
   }
 };
 
+// src/reason/prompt.ts
+var import_prompts2 = require("@kortyx/prompts");
+function normalizePromptReasonArgs(args) {
+  if (!("prompt" in args)) return args;
+  if (args.input !== void 0 || args.system !== void 0 || "messages" in args)
+    throw new import_prompts2.PromptError(
+      "PROMPT_REASON_CONFLICT",
+      "Use either prompt or input/system/messages in useReason."
+    );
+  const { prompt, ...rest } = args;
+  if (!(0, import_prompts2.isCompiledPrompt)(prompt))
+    throw new import_prompts2.PromptError(
+      "PROMPT_REASON_INVALID",
+      "useReason requires a compiled prompt returned by usePrompt."
+    );
+  return {
+    ...rest,
+    input: prompt.format === "system-user" ? prompt.user ?? "" : prompt.messages.filter((message) => message.role === "user").at(-1)?.content ?? "",
+    ...prompt.format === "system-user" ? { system: prompt.system } : { messages: structuredClone(prompt.messages) },
+    telemetry: {
+      ...args.telemetry,
+      prompt: {
+        name: prompt.ref.id,
+        version: prompt.ref.version,
+        type: prompt.format === "chat" ? "chat" : "text",
+        source: prompt.ref.source,
+        metadata: (0, import_prompts2.promptUsageMetadata)(prompt)
+      }
+    }
+  };
+}
+
 // src/reason/prompting.ts
 var import_zod4 = require("zod");
 var tryStringify2 = (value) => {
@@ -2823,19 +2999,34 @@ var normalizeToolResult = (toolCall, value) => {
     ...value !== void 0 && value !== null && typeof value === "object" && !Array.isArray(value) ? { structuredContent: value } : {}
   };
 };
-var createInitialMessages = (args) => [
-  ...typeof args.system === "string" || args.interruptInstructions || args.outputInstructions ? [
-    {
-      role: "system",
-      content: [
-        args.system,
-        args.interruptInstructions,
-        args.outputInstructions
-      ].filter((value) => Boolean(value)).join("\n\n")
-    }
-  ] : [],
-  { role: "user", content: String(args.input ?? "") }
-];
+var createInitialMessages = (args) => {
+  if (args.messages) {
+    const ordered = args.messages.map((message) => ({ ...message }));
+    const lastUser = ordered.reduce(
+      (last, message, position) => message.role === "user" ? position : last,
+      -1
+    );
+    if (args.inputOverride && lastUser >= 0)
+      ordered[lastUser] = { ...ordered[lastUser], content: args.input };
+    const instructions = [args.interruptInstructions, args.outputInstructions].filter(Boolean).join("\n\n");
+    if (instructions)
+      ordered.unshift({ role: "system", content: instructions });
+    return ordered;
+  }
+  return [
+    ...typeof args.system === "string" || args.interruptInstructions || args.outputInstructions ? [
+      {
+        role: "system",
+        content: [
+          args.system,
+          args.interruptInstructions,
+          args.outputInstructions
+        ].filter((value) => Boolean(value)).join("\n\n")
+      }
+    ] : [],
+    { role: "user", content: String(args.input ?? "") }
+  ];
+};
 var runReasonToolLoop = async (args) => {
   const { useReasonArgs, id, traceSpan, checkpointKey } = args;
   const ctx = getHookContext();
@@ -2977,6 +3168,8 @@ var runReasonToolLoop = async (args) => {
   let completed = false;
   const maxSteps = Math.max(1, useReasonArgs.toolExecution?.maxSteps ?? 3);
   const messages = checkpoint?.messages ?? createInitialMessages({
+    messages: useReasonArgs.messages,
+    inputOverride: Boolean(useReasonArgs.outputSchema),
     system: useReasonArgs.system,
     input: useReasonArgs.outputSchema ? withOutputGuardrails(useReasonArgs.input, useReasonArgs.outputSchema) : useReasonArgs.input,
     ...interruptConfig ? {
@@ -3011,7 +3204,7 @@ var runReasonToolLoop = async (args) => {
   let finalRaw;
   let finalOutput;
   let aggregatedUsage = steps.reduce(
-    (usage, step) => mergeUsage(usage, step.usage),
+    (usage2, step) => mergeUsage(usage2, step.usage),
     void 0
   );
   let finalFinishReason;
@@ -4114,7 +4307,10 @@ async function runReason(args) {
     }
   );
 }
-async function useReason(args) {
+async function useReason(request) {
+  const args = normalizePromptReasonArgs(
+    request
+  );
   try {
     return await runReason(args);
   } finally {
@@ -4419,6 +4615,38 @@ function reportError(error, options = {}) {
   }
 }
 
+// src/use-prompt.ts
+var import_prompts3 = require("@kortyx/prompts");
+async function usePrompt(reference, options) {
+  const ctx = getHookContext();
+  if (!ctx.node.prompts)
+    throw new import_prompts3.PromptError(
+      "PROMPT_SOURCE_NOT_CONFIGURED",
+      "Configure createAgent({ prompts: createPrompts(...) }) before calling usePrompt."
+    );
+  const stored = ctx.workflowState.__promptSnapshot;
+  const snapshot = await ctx.node.prompts.snapshot(stored);
+  if (!stored) {
+    ctx.workflowState.__promptSnapshot = snapshot;
+    ctx.stateDirty = true;
+  }
+  const key = `__promptPin:${reference.id}:${options.version ?? "assignment"}`;
+  const pin = options.version !== void 0 ? await ctx.node.prompts.pin(
+    reference.id,
+    options.version,
+    ctx.workflowState[key]
+  ) : void 0;
+  if (pin && !ctx.workflowState[key]) {
+    ctx.workflowState[key] = pin;
+    ctx.stateDirty = true;
+  }
+  return ctx.node.prompts.resolve(reference, {
+    ...options,
+    stored: snapshot,
+    ...pin ? { pin } : {}
+  });
+}
+
 // src/workflow.ts
 var import_node_crypto6 = require("crypto");
 var import_core8 = require("@kortyx/core");
@@ -4574,14 +4802,14 @@ async function runWorkflowCall(args, task) {
       ...content
     });
   };
-  const recordUsage = (usage) => {
-    if (!usage) return;
+  const recordUsage = (usage2) => {
+    if (!usage2) return;
     accumulateTokenUsage({
-      input: usage.input - (record.usage?.input ?? 0),
-      output: usage.output - (record.usage?.output ?? 0),
-      total: usage.total - (record.usage?.total ?? 0)
+      input: usage2.input - (record.usage?.input ?? 0),
+      output: usage2.output - (record.usage?.output ?? 0),
+      total: usage2.total - (record.usage?.total ?? 0)
     });
-    record.usage = usage;
+    record.usage = usage2;
   };
   const cached = record.status === "completed";
   try {
@@ -4702,6 +4930,7 @@ async function runWorkflowCall(args, task) {
   useAbortSignal,
   useInterrupt,
   useNodeState,
+  usePrompt,
   useReason,
   useRuntimeContext,
   useStructuredData,