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.input | the workflow's validated input |
ctx.approve({ title, description? }) | TanStack's yes-or-no approval → { approved, feedback? } |
ctx.headless | true 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:
| code | when |
|---|---|
INVALID_INPUT | the answer was rejected; the run did not move |
NOT_FOUND | no run with that id |
NO_ANSWER | an 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 |