defineSettings(schema) — introspection for tunable Workflows and Steps

[Pom4H]

A tiny helper to pair a Zod schema with a hook, so dashboards can discover shapes and render a settings UI at runtime—no hard-coded forms, no new transport.

import { z } from "zod";
import { defineSettings } from "workflow/experimental"; // thin sugar over defineHook()

export const emailSettings = defineSettings(
  z.object({
    from: z.string().email(),
    maxRetries: z.number().int().min(0).max(10).default(3),
    throttleRps: z.number().int().min(1).default(5),
  })
);

export async function sendEmailWorkflow() {
  "use workflow";
  const { from, maxRetries, throttleRps } = await emailSettings.create(); // await/resume as with hooks
  await sendEmail.withRetries(maxRetries)({ from, throttleRps });
}

async function sendEmail(args: { from: string; throttleRps: number }) {
  "use step";
}

Introspection: emailSettings.schema (Zod → JSON) lets UIs auto-generate forms.
Determinism: resolved values become explicit step inputs and are recorded before execution; replays read the same inputs. Existing retries/errors stay unchanged.
DX: treat business config like public fields (easy to tune), while infra complexity stays behind sane defaults.
Next: enables AI-assisted configuration (propose defaults, validate ranges, surface diffs) before resuming the waiting settings hook.

[pranaygp]

@TooTallNate and I would actually like to have the existing defineHook accept an optional zod schema. In addition to the type safety, the zod schema can actually be converted into a jsonschema and store in the world, and then when you try to resume the hook, the schema can can be used to prevent the resumption fully client side without unnecessarily triggering a network hop/adding to the workflow event log

[pranaygp]

Would that work for you @Pom4H? if so, would you also like to take a stab at implementing it with a PR?

re: the withRetries thing you proposed. I actually don't think steps should support that, but instead, you can already implement it like this:

import { getStepMetadata, FatalError } from "workflow";

async function sendEmail(from: string, throttleRps: number, maxRetries: number = 3) {
  "use step";

  const { attempt } = getStepMetadata();
  if (attempt >= maxRetries) {
    throw new FatalError("Max retries exceeded");
  }

  // ...
}

sendEmail.maxRetries = Number.POSITIVE_INFINITY; // or a very large number

[Pom4H]

I’m building a code-first workflow platform (admins curate build-time settings; operators/users run flows within those guards). Your suggestion to let defineHook accept an optional Zod schema exactly fits my need: it gives types, JSON Schema for introspection/UI, and client-side gating before resumption—keeping runs deterministic and the event log clean. I’m happy to take a stab at a PR.

@pranaygp Thanks for the awesome DX ❤️

[TooTallNate]

I'm a bit on the fence personally since this can be done in user-land easily enough. But AI SDK for example has already set precedent for allowing schemas so I think I'd be ok with it.