@noetic-tools/core 5.7.0 → 5.9.0

package/dist/adapters/openrouter.d.ts

@@ -77,6 +77,7 @@ export declare function executeToolCall(params: ExecuteToolCallParams): Promise<
  * @param apiKey - OpenRouter API key.
  * @param embeddingModel - Model identifier (default: `'openai/text-embedding-3-small'`).
  * @returns An `EmbedFn` that produces embedding vectors for the given texts.
+ * @throws `NoeticConfigError` with code `MISSING_API_KEY` if `apiKey` is empty or omitted.
  */
 export declare function createOpenRouterEmbed(apiKey?: string, embeddingModel?: string): EmbedFn;
 export {};

package/dist/adapters/openrouter.js

@@ -407,6 +407,7 @@ export async function executeToolCall(params) {
  * @param apiKey - OpenRouter API key.
  * @param embeddingModel - Model identifier (default: `'openai/text-embedding-3-small'`).
  * @returns An `EmbedFn` that produces embedding vectors for the given texts.
+ * @throws `NoeticConfigError` with code `MISSING_API_KEY` if `apiKey` is empty or omitted.
  */
 export function createOpenRouterEmbed(apiKey, embeddingModel) {
     if (!apiKey) {

package/dist/builders/channel-builder.d.ts

@@ -34,3 +34,21 @@ export declare function channel<T>(name: string, opts: {
     capacity?: number;
     external?: false;
 }): Channel<T>;
+/**
+ * Creates a typed communication channel whose externality is decided at run
+ * time. Pass a literal `true`/`false` to get the narrowed return type instead.
+ *
+ * @public
+ * @param name - Channel name for identification and debugging.
+ * @param opts.schema - Zod schema used to validate every message sent through the channel.
+ * @param opts.mode - Delivery semantics: `'value'` (last-write-wins), `'queue'` (FIFO), `'topic'` (pub/sub).
+ * @param opts.capacity - Buffer size for queue mode (default: 1000). Ignored for value/topic modes.
+ * @param opts.external - `true` for an externally writable channel; omit or `false` otherwise.
+ * @returns An `ExternalChannel` when `external` is `true`, otherwise a `Channel`.
+ */
+export declare function channel<T>(name: string, opts: {
+    schema: ZodType<T>;
+    mode: 'value' | 'queue' | 'topic';
+    capacity?: number;
+    external?: boolean;
+}): Channel<T> | ExternalChannel<T>;

package/dist/builders/control-flow-builders.d.ts

@@ -1,5 +1,16 @@
 import type { ContextData } from '@noetic-tools/context';
-import type { Context, ExecuteStepFn, SettleResult, Step, StepConditional, StepInParallelAll, StepInParallelRace, StepInParallelSettle } from '@noetic-tools/types';
+import type { StepConditional, StepInParallelAll, StepInParallelRace, StepInParallelSettle } from '@noetic-tools/types';
+/**
+ * Options for `inParallel()`, one shape per mode. `merge` is required for `all`
+ * and `settle` and absent for `race`.
+ * @public
+ */
+export type InParallelOpts<TContext = ContextData, I = unknown, O = unknown> = InParallelRaceOpts<TContext, I, O> | InParallelAllOpts<TContext, I, O> | InParallelSettleOpts<TContext, I, O>;
+type InParallelRaceOpts<TContext, I, O> = Omit<StepInParallelRace<TContext, I, O>, 'kind'>;
+type InParallelAllOpts<TContext, I, O> = Omit<StepInParallelAll<TContext, I, O>, 'kind'>;
+type InParallelSettleOpts<TContext, I, O> = Omit<StepInParallelSettle<TContext, I, O>, 'kind'>;
+/** @public Options for `conditional()`. */
+export type ConditionalOpts<TContext = ContextData, I = unknown, O = unknown> = Omit<StepConditional<TContext, I, O>, 'kind'>;
 /**
  * Creates a parallel execution step that races paths and returns the first result.
  *
@@ -11,13 +22,7 @@ import type { Context, ExecuteStepFn, SettleResult, Step, StepConditional, StepI
  * @returns A `StepInParallelRace` step.
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  */
-export declare function inParallel<TContext = ContextData, I = unknown, O = unknown>(opts: {
-    id: string;
-    mode: 'race';
-    paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
-    concurrency?: number;
-    _optimizable?: Step<TContext>[];
-}): StepInParallelRace<TContext, I, O>;
+export declare function inParallel<TContext = ContextData, I = unknown, O = unknown>(opts: InParallelRaceOpts<TContext, I, O>): StepInParallelRace<TContext, I, O>;
 /**
  * Creates a parallel execution step that waits for all paths and merges results.
  *
@@ -31,14 +36,7 @@ export declare function inParallel<TContext = ContextData, I = unknown, O = unkn
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_MERGE_FUNCTION` if `merge` is not provided.
  */
-export declare function inParallel<TContext = ContextData, I = unknown, O = unknown>(opts: {
-    id: string;
-    mode: 'all';
-    paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
-    merge: (results: O[], ctx: Context<TContext>) => O;
-    concurrency?: number;
-    _optimizable?: Step<TContext>[];
-}): StepInParallelAll<TContext, I, O>;
+export declare function inParallel<TContext = ContextData, I = unknown, O = unknown>(opts: InParallelAllOpts<TContext, I, O>): StepInParallelAll<TContext, I, O>;
 /**
  * Creates a parallel execution step that waits for all paths, collecting errors as results.
  *
@@ -52,14 +50,7 @@ export declare function inParallel<TContext = ContextData, I = unknown, O = unkn
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_MERGE_FUNCTION` if `merge` is not provided.
  */
-export declare function inParallel<TContext = ContextData, I = unknown, O = unknown>(opts: {
-    id: string;
-    mode: 'settle';
-    paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
-    merge: (results: SettleResult<O>[], ctx: Context<TContext>) => O;
-    concurrency?: number;
-    _optimizable?: Step<TContext>[];
-}): StepInParallelSettle<TContext, I, O>;
+export declare function inParallel<TContext = ContextData, I = unknown, O = unknown>(opts: InParallelSettleOpts<TContext, I, O>): StepInParallelSettle<TContext, I, O>;
 /**
  * Creates a conditional routing step that selects the next step at runtime.
  *
@@ -72,9 +63,5 @@ export declare function inParallel<TContext = ContextData, I = unknown, O = unkn
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_ROUTE_FUNCTION` if `route` is not provided.
  */
-export declare function conditional<TContext = ContextData, I = unknown, O = unknown>(opts: {
-    id: string;
-    route: (input: I, ctx: Context<TContext>, run: ExecuteStepFn) => Step<TContext, I, O> | null | Promise<Step<TContext, I, O> | null>;
-    _optimizable?: Step<TContext>[];
-    _rebuild?: (children: Step<TContext>[]) => StepConditional<TContext, I, O>;
-}): StepConditional<TContext, I, O>;
+export declare function conditional<TContext = ContextData, I = unknown, O = unknown>(opts: ConditionalOpts<TContext, I, O>): StepConditional<TContext, I, O>;
+export {};

package/dist/builders/decide-builders.d.ts

@@ -1,6 +1,6 @@
-import type { AnsweredAll, CaseKeyOf, Context, ContextData, DecideQuestions, DecideStep, DecideView, Lazy, ProjectionPolicy, Step, StepConditional } from '@noetic-tools/types';
+import type { AnsweredAll, CaseKeyOf, Context, ContextData, DecideQuestions, DecideStep, DecideView, Lazy, ProjectionPolicy, Step, StepConditional, StepReplay } from '@noetic-tools/types';
 /** @public Options for `decide()`. */
-export interface StepDecideOpts<TContext, Q extends DecideQuestions> {
+export interface StepDecideOpts<TContext, Q extends DecideQuestions, I = unknown> extends StepReplay<TContext, I> {
     id: string;
     /** Decision model id. Falls back to `harness.config.decisionModel`. */
     model?: Lazy<string, TContext>;
@@ -38,7 +38,7 @@ type OnlyKeys<Cases, Keys extends PropertyKey> = {
  * @public `routeSwitch` options that route by one question. `cases` needs exactly
  * one step per outcome; refusals and low-confidence answers take `uncertain`.
  */
-export interface RouteSwitchByKeyOpts<TContext, Q extends DecideQuestions, K extends keyof Q & string, Cases extends Record<CaseKeyOf<Q[K]>, CaseStep>, U extends CaseStep> {
+export interface RouteSwitchByKeyOpts<TContext, Q extends DecideQuestions, K extends keyof Q & string, Cases extends Record<CaseKeyOf<Q[K]>, CaseStep>, U extends CaseStep> extends StepReplay<TContext> {
     id: string;
     decide: DecideStep<TContext, unknown, Q>;
     on: K;
@@ -49,7 +49,7 @@ export interface RouteSwitchByKeyOpts<TContext, Q extends DecideQuestions, K ext
     uncertain: U;
 }
 /** @public `routeSwitch` options that combine answers in a function; `default` catches the rest. */
-export interface RouteSwitchByFunctionOpts<TContext, Q extends DecideQuestions, C extends string, Cases extends Partial<Record<C, CaseStep>>, D extends CaseStep, U extends CaseStep> {
+export interface RouteSwitchByFunctionOpts<TContext, Q extends DecideQuestions, C extends string, Cases extends Partial<Record<C, CaseStep>>, D extends CaseStep, U extends CaseStep> extends StepReplay<TContext> {
     id: string;
     decide: DecideStep<TContext, unknown, Q>;
     /** Receives answers with refusals already handled. */
@@ -71,7 +71,7 @@ export interface RouteSwitchByFunctionOpts<TContext, Q extends DecideQuestions,
  * @throws `NoeticConfigError` `EMPTY_STEP_ID`, `MISSING_MODEL` (empty eager model),
  *   `INVALID_DECIDE_QUESTIONS`, or `INVALID_DECIDE_SAMPLES`.
  */
-export declare function decide<const Q extends DecideQuestions, TContext = ContextData, I = unknown>(opts: StepDecideOpts<TContext, Q>): DecideStep<TContext, I, Q>;
+export declare function decide<const Q extends DecideQuestions, TContext = ContextData, I = unknown>(opts: StepDecideOpts<TContext, Q, I>): DecideStep<TContext, I, Q>;
 /**
  * Creates a conditional step that runs a decide step and routes the original input to
  * the case its answers pick. The output type is the union of every case's

package/dist/builders/decide-builders.js

@@ -59,6 +59,8 @@ export function routeSwitch(opts) {
         minConfidence: 'minConfidence' in opts ? opts.minConfidence : undefined,
         uncertain: opts.uncertain,
         default: 'default' in opts ? opts.default : undefined,
+        durable: opts.durable,
+        replayKey: opts.replayKey,
     });
 }
 /**
@@ -84,6 +86,8 @@ function buildSwitch(plan) {
     ];
     return conditional({
         id: plan.id,
+        durable: plan.durable,
+        replayKey: plan.replayKey,
         route: async (input, ctx, run) => {
             const answers = frameworkCast(await run(plan.decide, input, ctx));
             const picked = pick(answers);

package/dist/builders/every.d.ts

@@ -1,5 +1,5 @@
 import type { ContextData } from '@noetic-tools/context';
-import type { Channel, ScheduleErrorPolicy, Step, StepSchedule } from '@noetic-tools/types';
+import type { Channel, ScheduleErrorPolicy, Step, StepReplay, StepSchedule } from '@noetic-tools/types';
 /**
  * Configuration options accepted by the `schedule()` builder, excluding the `kind`
  * discriminant. `schedule()` schedules a body step on a fixed-interval, optionally
@@ -7,7 +7,7 @@ import type { Channel, ScheduleErrorPolicy, Step, StepSchedule } from '@noetic-t
  *
  * @public
  */
-export interface ScheduleOptions<TContext = ContextData, I = unknown, O = unknown> {
+export interface ScheduleOptions<TContext = ContextData, I = unknown, O = unknown> extends StepReplay<TContext, I> {
     /** Unique step identifier used in traces and error messages. */
     id: string;
     /** Body step executed on each iteration. */

package/dist/builders/every.js

@@ -57,6 +57,8 @@ export function schedule(opts) {
         inbox: opts.inbox,
         onError: opts.onError ?? 'continue',
         jitter: opts.jitter ?? 0,
+        durable: opts.durable,
+        replayKey: opts.replayKey,
     };
     getDefaultRegistrar().register(built);
     return built;

package/dist/builders/loop-builder.d.ts

@@ -10,7 +10,7 @@ export type LoopConfig<TContext = ContextData, I = unknown, O = unknown> = Omit<
  * @param opts.steps - Array of steps to execute sequentially on each iteration.
  * @param opts.until - Termination predicate `(snapshot) => Verdict | Promise<Verdict>` evaluated after each iteration.
  * @param opts.maxIterations - Hard safety cap on iterations (default: 1000).
- * @param opts.maxHistorySize - Maximum entries kept in the snapshot history array.
+ * @param opts.maxHistorySize - Maximum entries kept in the snapshot history array (default: 100); oldest drop first.
  * @param opts.inbox - Optional channel for injecting messages into the loop mid-execution.
  * @param opts.parkTimeout - Ms to wait on inbox before the loop parks itself (default: 0).
  * @param opts.prepareNext - Transforms `(output, verdict, ctx)` into the next iteration's input.

package/dist/builders/loop-builder.js

@@ -8,7 +8,7 @@ import { getDefaultRegistrar } from '../types/step-registrar.js';
  * @param opts.steps - Array of steps to execute sequentially on each iteration.
  * @param opts.until - Termination predicate `(snapshot) => Verdict | Promise<Verdict>` evaluated after each iteration.
  * @param opts.maxIterations - Hard safety cap on iterations (default: 1000).
- * @param opts.maxHistorySize - Maximum entries kept in the snapshot history array.
+ * @param opts.maxHistorySize - Maximum entries kept in the snapshot history array (default: 100); oldest drop first.
  * @param opts.inbox - Optional channel for injecting messages into the loop mid-execution.
  * @param opts.parkTimeout - Ms to wait on inbox before the loop parks itself (default: 0).
  * @param opts.prepareNext - Transforms `(output, verdict, ctx)` into the next iteration's input.

package/dist/builders/provide-builder.d.ts

@@ -1,5 +1,5 @@
 import type { ContextConfig, ContextData, ContextLayer } from '@noetic-tools/context';
-import type { Step, StepWithContext } from '@noetic-tools/types';
+import type { Step, StepReplay, StepWithContext } from '@noetic-tools/types';
 /**
  * Creates a provide step that attaches context layers to its child without creating an isolated context.
  * Like React's Context.Provider — layers are available to all descendant steps.
@@ -12,9 +12,10 @@ import type { Step, StepWithContext } from '@noetic-tools/types';
  * @returns A `StepWithContext` step.
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_CHILD_STEP` if `child` is not provided.
+ * @throws `NoeticConfigError` with code `MISSING_CONTEXT_LAYERS` if `context` is not provided.
  */
 export declare function withContext<TContext = ContextData, I = unknown, O = unknown>(opts: {
     id: string;
     child: Step<TContext, I, O>;
     context: ContextConfig | ContextLayer[];
-}): StepWithContext<TContext, I, O>;
+} & StepReplay<TContext, I>): StepWithContext<TContext, I, O>;

package/dist/builders/provide-builder.js

@@ -12,6 +12,7 @@ import { getDefaultRegistrar } from '../types/step-registrar.js';
  * @returns A `StepWithContext` step.
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_CHILD_STEP` if `child` is not provided.
+ * @throws `NoeticConfigError` with code `MISSING_CONTEXT_LAYERS` if `context` is not provided.
  */
 export function withContext(opts) {
     if (!opts.id?.trim()) {
@@ -41,6 +42,8 @@ export function withContext(opts) {
         id: opts.id,
         child: opts.child,
         context: layers,
+        durable: opts.durable,
+        replayKey: opts.replayKey,
     };
     getDefaultRegistrar().register(built);
     return built;

package/dist/builders/spawn-builder.d.ts

@@ -1,6 +1,6 @@
 import type { ContextConfig, ContextData, ContextLayer } from '@noetic-tools/context';
-import type { Step, StepSpawn, SubprocessAdapter } from '@noetic-tools/types';
-interface SpawnOpts<TContext, I, O> {
+import type { Step, StepReplay, StepSpawn, SubprocessAdapter } from '@noetic-tools/types';
+interface SpawnOpts<TContext, I, O> extends StepReplay<TContext, I> {
     id: string;
     child: Step<TContext, I, O>;
     context?: ContextConfig | ContextLayer[];
@@ -26,7 +26,6 @@ interface SpawnOpts<TContext, I, O> {
  *   can dispatch either by id.
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_CHILD_STEP` if `child` is not provided.
- * @throws `NoeticConfigError` with code `DUPLICATE_STEP_ID` if another step with the same id is already registered.
  */
 export declare function spawn<TContext = ContextData, I = unknown, O = unknown>(opts: SpawnOpts<TContext, I, O>): StepSpawn<TContext, I, O>;
 export {};

package/dist/builders/spawn-builder.js

@@ -16,7 +16,6 @@ import { getDefaultRegistrar } from '../types/step-registrar.js';
  *   can dispatch either by id.
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_CHILD_STEP` if `child` is not provided.
- * @throws `NoeticConfigError` with code `DUPLICATE_STEP_ID` if another step with the same id is already registered.
  */
 export function spawn(opts) {
     if (!opts.id?.trim()) {
@@ -40,6 +39,8 @@ export function spawn(opts) {
         context: opts.context,
         timeout: opts.timeout,
         subprocess: opts.subprocess,
+        durable: opts.durable,
+        replayKey: opts.replayKey,
     };
     getDefaultRegistrar().register(built);
     // Ensure the child is addressable by id — builders for `runCode`/`callModel`/`invokeTool`

package/dist/builders/step-builders.d.ts

@@ -1,6 +1,6 @@
 import type { ContextData } from '@noetic-tools/context';
-import type { AcpAgent, AcpClientCapabilityConfig, AcpContentBlock, AcpMcpServer, AcpPermissionHandler, AcpPermissionPolicy, AcpSessionPolicy, Context, Lazy, ModelParams, OutputCodec, RetryPolicy, ServerToolSpec, StandardSchemaV1, StepAcpAgent, StepCallModel, StepInvokeTool, StepRunCode, SubprocessAdapter, Tool } from '@noetic-tools/types';
-export interface RunCodeOpts<TContext, I, O> {
+import type { AcpAgent, AcpClientCapabilityConfig, AcpContentBlock, AcpMcpServer, AcpPermissionHandler, AcpPermissionPolicy, AcpSessionPolicy, Context, Lazy, ModelParams, OutputCodec, RetryPolicy, ServerToolSpec, StandardSchemaV1, StepAcpAgent, StepCallModel, StepInvokeTool, StepReplay, StepRunCode, SubprocessAdapter, Tool } from '@noetic-tools/types';
+export interface RunCodeOpts<TContext, I, O> extends StepReplay<TContext, I> {
     id: string;
     execute: (input: I, ctx: Context<TContext>) => Promise<O>;
     retry?: RetryPolicy;
@@ -11,7 +11,7 @@ export interface RunCodeOpts<TContext, I, O> {
      */
     subprocess?: SubprocessAdapter;
 }
-export interface CallModelOpts<TContext, O> {
+export interface CallModelOpts<TContext, O, I = unknown> extends StepReplay<TContext, I> {
     id: string;
     /** Model id. Eager string or `(ctx) => string` getter (resolved at step execution). */
     model: Lazy<string, TContext>;
@@ -33,12 +33,12 @@ export interface CallModelOpts<TContext, O> {
     params?: ModelParams;
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
 }
-export interface InvokeToolOpts<I, O> {
+export interface InvokeToolOpts<I, O, TContext = ContextData> extends StepReplay<TContext, I> {
     id: string;
     tool: Tool<StandardSchemaV1<unknown, I>, StandardSchemaV1<unknown, O>>;
     args?: Partial<I>;
 }
-export interface StepAcpAgentOpts<TContext, O> {
+export interface StepAcpAgentOpts<TContext, O, I = unknown> extends StepReplay<TContext, I> {
     id: string;
     /** An ACP agent adapter, e.g. `claudeCode()` from `@noetic-tools/acp`. Eager or `(ctx) => AcpAgent`. */
     agent: Lazy<AcpAgent, TContext>;
@@ -83,7 +83,6 @@ export interface StepAcpAgentOpts<TContext, O> {
  *   adapter can dispatch it by id.
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_EXECUTE_FUNCTION` if `execute` is not provided.
- * @throws `NoeticConfigError` with code `DUPLICATE_STEP_ID` if another step with the same id is already registered with a different body.
  */
 export declare function runCode<TContext = ContextData, I = unknown, O = unknown>(opts: RunCodeOpts<TContext, I, O>): StepRunCode<TContext, I, O>;
 /**
@@ -101,7 +100,7 @@ export declare function runCode<TContext = ContextData, I = unknown, O = unknown
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_MODEL` if an eager `model` string is empty. Function-form models are validated at step execution.
  */
-export declare function callModel<TContext = ContextData, I = unknown, O = unknown>(opts: CallModelOpts<TContext, O>): StepCallModel<TContext, I, O>;
+export declare function callModel<TContext = ContextData, I = unknown, O = unknown>(opts: CallModelOpts<TContext, O, I>): StepCallModel<TContext, I, O>;
 /**
  * Creates a tool execution step that invokes a typed tool definition.
  *
@@ -114,7 +113,7 @@ export declare function callModel<TContext = ContextData, I = unknown, O = unkno
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_TOOL` if `tool` is not provided.
  */
-export declare function invokeTool<TContext = ContextData, I = unknown, O = unknown>(opts: InvokeToolOpts<I, O>): StepInvokeTool<TContext, I, O>;
+export declare function invokeTool<TContext = ContextData, I = unknown, O = unknown>(opts: InvokeToolOpts<I, O, TContext>): StepInvokeTool<TContext, I, O>;
 /**
  * The ACP step builder namespace. Unlike the flattened base builders
  * (`runCode`, `callModel`, `invokeTool`), the coding-agent builder stays
@@ -140,5 +139,5 @@ export declare const step: {
      * @returns A `StepAcpAgent`, auto-registered in the step registry.
      * @throws `NoeticConfigError` `EMPTY_STEP_ID` / `MISSING_ACP_AGENT` / `MISSING_PROMPT`.
      */
-    acpAgent<TContext = ContextData, I = unknown, O = unknown>(opts: StepAcpAgentOpts<TContext, O>): StepAcpAgent<TContext, I, O>;
+    acpAgent<TContext = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepAcpAgentOpts<TContext, O, I>): StepAcpAgent<TContext, I, O>;
 };

package/dist/builders/step-builders.js

@@ -46,7 +46,6 @@ function validateAcpAgentOpts(opts) {
  *   adapter can dispatch it by id.
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_EXECUTE_FUNCTION` if `execute` is not provided.
- * @throws `NoeticConfigError` with code `DUPLICATE_STEP_ID` if another step with the same id is already registered with a different body.
  */
 export function runCode(opts) {
     if (!opts.id || opts.id.trim() === '') {

package/dist/builders/tool-builder.d.ts

@@ -51,6 +51,8 @@ type GeneratorToolConfig<I extends StandardSchemaV1, E extends StandardSchemaV1,
  * Accepts Zod, Valibot, or any Standard Schema v1 implementation.
  *
  * @public
+ * @throws `NoeticConfigError` with code `EMPTY_TOOL_NAME` if `name` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_EXECUTE_FUNCTION` if `execute` is not provided.
  */
 export declare function tool<I extends StandardSchemaV1, O extends StandardSchemaV1>(config: ToolConfig<I, O>): Tool<I, O>;
 /**

package/dist/builders/tool-builder.js

@@ -24,6 +24,8 @@ function validateToolConfig(name, execute) {
  * Accepts Zod, Valibot, or any Standard Schema v1 implementation.
  *
  * @public
+ * @throws `NoeticConfigError` with code `EMPTY_TOOL_NAME` if `name` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_EXECUTE_FUNCTION` if `execute` is not provided.
  */
 export function tool(config) {
     validateToolConfig(config.name, config.execute);

package/dist/builders/workflow-hydrator.js

@@ -16,6 +16,7 @@ import { loop } from './loop-builder.js';
 import { withContext } from './provide-builder.js';
 import { spawn } from './spawn-builder.js';
 import { callModel, runCode, step } from './step-builders.js';
+import { workflowReplayKey } from './workflow-replay-key.js';
 //#endregion
 //#region Until Predicate Hydration
 function hydrateUntilPredicate(pred) {
@@ -99,13 +100,15 @@ function hydrateCallModelNode(node, ctx) {
  * runtime still returns the codec's real value. This is the same erasure the
  * rest of the hydrator applies via `frameworkCast`.
  */
-function availableLibraries(ctx) {
-    if (!ctx.uiLibraries || ctx.uiLibraries.size === 0) {
-        return '(none)';
+/** A complete sentence naming what is registered, for a hint. */
+function registeredSentence(noun, names) {
+    const list = [
+        ...names,
+    ];
+    if (list.length === 0) {
+        return `No ${noun} are registered.`;
     }
-    return [
-        ...ctx.uiLibraries.keys(),
-    ].join(', ');
+    return `Registered ${noun}: ${list.join(', ')}.`;
 }
 function resolveOutputCodec(ref, nodeId, ctx) {
     if (!ref) {
@@ -118,7 +121,7 @@ function resolveOutputCodec(ref, nodeId, ctx) {
     throw new NoeticConfigError({
         code: 'UNKNOWN_UI_LIBRARY_REFERENCE',
         message: `UI library '${ref.library}' referenced in workflow node '${nodeId}' is not registered.`,
-        hint: `Pass output codecs via HydrationContext.uiLibraries, e.g. new Map([['${ref.library}', openUi(myLibrary)]]) from @noetic-tools/openui. Available: ${availableLibraries(ctx)}`,
+        hint: `Pass output codecs via HydrationContext.uiLibraries, e.g. new Map([['${ref.library}', openUi(myLibrary)]]) from @noetic-tools/openui. ${registeredSentence('UI libraries', ctx.uiLibraries?.keys() ?? [])}`,
     });
 }
 function hydrateInvokeToolNode(node, ctx) {
@@ -130,9 +133,7 @@ function hydrateInvokeToolNode(node, ctx) {
         throw new NoeticConfigError({
             code: 'UNKNOWN_TOOL_REFERENCE',
             message: `Tool '${node.toolName}' referenced in workflow node '${node.id}' is not registered.`,
-            hint: `Available tools: ${[
-                ...ctx.tools.keys(),
-            ].join(', ') || '(none)'}`,
+            hint: `Register '${node.toolName}' in HydrationContext.tools before hydrating. ${registeredSentence('tools', ctx.tools.keys())}`,
         });
     }
     return frameworkCast(runCode({
@@ -533,9 +534,7 @@ function resolveTools(toolNames, registry) {
             throw new NoeticConfigError({
                 code: 'UNKNOWN_TOOL_REFERENCE',
                 message: `Tool '${name}' referenced in workflow is not registered.`,
-                hint: `Available tools: ${[
-                    ...registry.keys(),
-                ].join(', ') || '(none)'}`,
+                hint: `Register '${name}' in HydrationContext.tools before hydrating. ${registeredSentence('tools', registry.keys())}`,
             });
         }
         return resolved;
@@ -767,7 +766,15 @@ export function hydrateNode(node, ctx) {
             hint: `Supported kinds: ${Object.keys(NODE_HYDRATORS).join(', ')}.`,
         });
     }
-    return hydrator(node, ctx);
+    const hydrated = hydrator(node, ctx);
+    // Set in place rather than copied: builders register the step object itself.
+    if (node.durable !== undefined) {
+        hydrated.durable = node.durable;
+    }
+    if (node.replayKey !== undefined) {
+        hydrated.replayKey = workflowReplayKey(node.id, node.replayKey);
+    }
+    return hydrated;
 }
 /**
  * Hydrates a complete `WorkflowDocument` into a live `Step` tree.

package/dist/builders/workflow-replay-key.d.ts

@@ -0,0 +1,15 @@
+import type { WorkflowReplayKey } from '@noetic-tools/types';
+/**
+ * Build the `replayKey` function a JSON node's declarative `replayKey` describes
+ * (spec 26 § Replay keys). The key is `<node id>:<hash of the selected input>`: the
+ * node id keeps two different nodes that read the same input from fighting over one
+ * ledger entry, while nodes that share an id — the same worker leaf written into
+ * several paths — share entries by design.
+ *
+ * The interpreter turns a throwing `replayKey` into a warning and runs the step
+ * without replay, so the step itself never fails.
+ *
+ * @throws `NoeticConfigError` with code `INVALID_REPLAY_KEY_INPUT` from the returned
+ * function, when `from` meets an input that is not a JSON object.
+ */
+export declare function workflowReplayKey(nodeId: string, spec: WorkflowReplayKey): (input: string) => string;

package/dist/builders/workflow-replay-key.js

@@ -0,0 +1,46 @@
+import { hashString, NoeticConfigError } from '@noetic-tools/types';
+/**
+ * Build the `replayKey` function a JSON node's declarative `replayKey` describes
+ * (spec 26 § Replay keys). The key is `<node id>:<hash of the selected input>`: the
+ * node id keeps two different nodes that read the same input from fighting over one
+ * ledger entry, while nodes that share an id — the same worker leaf written into
+ * several paths — share entries by design.
+ *
+ * The interpreter turns a throwing `replayKey` into a warning and runs the step
+ * without replay, so the step itself never fails.
+ *
+ * @throws `NoeticConfigError` with code `INVALID_REPLAY_KEY_INPUT` from the returned
+ * function, when `from` meets an input that is not a JSON object.
+ */
+export function workflowReplayKey(nodeId, spec) {
+    if (spec === true) {
+        return (input) => `${nodeId}:${hashString(asText(input))}`;
+    }
+    return (input) => {
+        const fields = inputObject(input, nodeId);
+        return `${nodeId}:${hashString(JSON.stringify(spec.from.map((key) => fields[key] ?? null)))}`;
+    };
+}
+/** JSON nodes pass strings, but a `decide` answer can arrive as an object. */
+function asText(input) {
+    return typeof input === 'string' ? input : JSON.stringify(input);
+}
+function inputObject(input, nodeId) {
+    const parsed = typeof input === 'string' ? parseJson(input) : input;
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new NoeticConfigError({
+            code: 'INVALID_REPLAY_KEY_INPUT',
+            message: `Node '${nodeId}' keys replay on input properties, but its input is not a JSON object.`,
+            hint: 'Use `"replayKey": true` to key on the whole input, or feed the node a JSON object.',
+        });
+    }
+    return Object.fromEntries(Object.entries(parsed));
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}