Skip to Content
onedef

API reference

Everything @onedef/elicitation-workflow exports.

Creating a workflow

import { createWorkflow } from '@onedef/elicitation-workflow'

const deploy = createWorkflow({ id: 'deploy', description?, input?: StandardSchema }).handler(async (ctx) => { … })

createWorkflow is TanStack Workflow's, with this package's middleware already applied. The builder is TanStack's, so .middleware([…]) adds more of your own.

On ctx

ctx.elicitHumanInput({ message, requestedSchema }, { id? })ask the user to fill a form → { action, content? }
ctx.elicitAgentInput(name, { schema, instructions?, data? })ask the agent for a value matching schema
ctx.step(name, fn)run fn once; on replay, return what it returned
ctx.inputthe workflow's validated input
ctx.approve({ title, description? })TanStack's yes-or-no approval → { approved, feedback? }
ctx.headlesstrue in a run started with { headless: true }

Already using TanStack Workflow directly? Add the questions to its createWorkflow with the middleware:

import { createWorkflow } from '@tanstack/workflow-core'          // TanStack's own
import { mcpElicitation } from '@onedef/elicitation-workflow'

const deploy = createWorkflow({ id: 'deploy' }).middleware([mcpElicitation()]).handler(async (ctx) => { … })

elicitHumanInput(ctx, params) and elicitAgentInput(ctx, name, options) are also exported as plain functions.

MCP: @onedef/elicitation-workflow/mcp

Registered like server.registerTool(name, config, handler), with the workflow as the handler:

registerWorkflowTool(server: McpServer, name: string, {
  runStore: RunStore,              // where runs wait between calls
  title?: string,
  description?: string,            // default: the workflow's description
  inputSchema?: StandardSchema,    // default: the workflow's input schema
  annotations?: ToolAnnotations,
}, workflow)

Registers the tool name, which starts a run with the workflow's input, and <name>_next ({ runId, payload? }), where the agent answers ctx.elicitAgentInput. A question for the user is returned as MCP's input_required, and the client's retry continues the run.

Driving runs

const runs = workflowRuns(workflow, { runStore })

runs.start(input, { headless?: boolean }): Promise<RunSnapshot>
runs.next(runId, answer?): Promise<RunSnapshot>
interface RunSnapshot<Output> {
  runId: string
  status: 'waiting' | 'done' | 'failed'
  waitingFor?:
    | { kind: 'agent'; name; instructions?; data?; schema }
    | { kind: 'human'; name; message; requestedSchema }
    | { kind: 'approval'; name; title; description? }
  output?: Output
  error?: { message: string; code?: string }
}

RunError has a code:

codewhen
INVALID_INPUTthe answer was rejected; the run did not move
NOT_FOUNDno run with that id
NO_ANSWERan agent question in a headless run (it fails the run)

Run stores

memoryRunStore()in process memory
kvRunStore(kv, { namespace? })on a key-value store; runs under namespace (default _runs)
redisRunStore(redis, { prefix?, ttlSeconds? })from /redis; default prefix onedef:, TTL 7 days

On this page