Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
@clerum/workflow-sdk
A TypeScript library for building custom workflow coordinator Pods that plug into the
evenfire/Clerum WorkflowRecipe runtime. A coordinator is the process that runs inside a
workflow's Pod: it loads the workflow spec from a mounted volume, resolves step order,
executes steps (either as deterministic in-coordinator logic or by delegating agentic work to
the mcp-host service), reports status back to the Workflow Runtime Controller (WRC), and
responds to control signals (pause / resume / cancel / approval). The SDK wires all of these
pieces together behind a single façade, WorkflowSDK, so your coordinator focuses only on step
business logic.
Install & prerequisites
- Node.js
>=20. @clerum/workflow-sdkdepends on@clerum/workflow-runtime-core, where the concrete implementations actually live. The SDK barrel re-exports the public runtime-core symbols (ConfigLoader,StepCoordinator,StatusReporter,SignalPoller,McpHostClient, the prompt/soul/model injection helpers, error types, and all the value/spec types); only theWorkflowSDKclass and the registry interfaces are defined in this package. Both packages must be present at runtime.- The dependency is declared as a local filesystem link
(
"@clerum/workflow-runtime-core": "file:../workflow-runtime-core") — runtime-core is an internal package that is not published on its own. As a result there is no standalonenpm install @clerum/workflow-sdkthat resolves for an outside consumer: installing from a registry would try to resolvefile:../workflow-runtime-core, which does not exist outside this repository, and fail. Consume the SDK from a checkout of this repository, where the sibling package resolves, and build your coordinator image from the repository root (see Building a coordinator image).
# From a clone of this repository, with both sibling packages present:
git clone <this-repo> && cd <this-repo>/packages/workflow-sdk
npm install # resolves the file: link to ../workflow-runtime-core
The runtime environment (env vars, token files, and the mounted spec volume) is injected by WRC when it schedules your Pod — you do not set these yourself.
Core concepts — the coordinator lifecycle
- Load config —
WorkflowSDK.fromEnvironment()reads required env vars, builds a token provider, initializes the logger, and wires every component.sdk.config.getSpec()reads and validates the workflow spec from the mounted volume (default/etc/workflow/config.json). - Poll signals —
sdk.signals(aSignalPoller) polls WRC for control signals; a local REST server started byfromEnvironment()can also receive pushed signals. - Coordinate steps —
sdk.coordinator.resolveOrder(spec.steps)computes a deterministic execution order (Kahn topological sort overstep.dependsOn, throwingCycleDetectedErroron cycles); your coordinator iterates the ordered steps. - Report status —
sdk.status(aStatusReporter) reports per-step and workflow-level phase transitions back to WRC. Mirror the same state locally withsdk.updatePhase()andsdk.updateStepState()so the REST/statusendpoint stays current.
Agentic (broker-backed) work is delegated through sdk.requireMcpHost() — the McpHostClient is
only constructed when both CLERUM_MCPHOST_URL and MCP_HOST_TOKEN_FILE are configured.
Environment variables (read by ConfigLoader)
Required (missing any throws WorkflowSDKInitError):
CLERUM_WORKFLOW_NAMECLERUM_NAMESPACECLERUM_WRC_URLWRC_TOKEN_FILE
Optional:
CLERUM_MCPHOST_URL+MCP_HOST_TOKEN_FILE— enable agentic steps (if the URL is set, the token file is required).CLERUM_SNIPPET_RUNNER_URL+SNIPPET_RUNNER_TOKEN_FILE— same pairing rule.CLERUM_CORRELATION_ID(defaults to a random UUID)CLERUM_SIGNAL_POLL_INTERVAL_MS(default5000, floor500)CLERUM_SDK_REST_PORT(default8090)CLERUM_REGISTRY_URL,CLERUM_STORAGE_ENDPOINTCLERUM_WORKFLOW_CONFIG_PATH/WORKFLOW_CONFIG_PATH(spec path; default/etc/workflow/config.json)
Quickstart
A minimal coordinator that loads the spec, runs each step in dependency order, and reports
status. This mirrors the shape of the canonical end-to-end fixture (with a trivial step executor
stubbed in — replace runStep with your own logic).
// coordinator.ts
import { type StepSpec, WorkflowSDK, emitLog } from '@clerum/workflow-sdk'
async function runStep(step: StepSpec): Promise<unknown> {
// Your deterministic business logic, or delegate agentic work to
// sdk.requireMcpHost().executeAgentStep({ ... }).
return { stepId: step.id, ok: true }
}
async function main(): Promise<void> {
const sdk = await WorkflowSDK.fromEnvironment()
const spec = await sdk.config.getSpec()
const orderedSteps = sdk.coordinator.resolveOrder(spec.steps)
try {
sdk.updatePhase('running')
await sdk.status.reportWorkflowStatus('running')
for (const step of orderedSteps) {
const startedMs = Date.now()
sdk.updateStepState(step.id, { phase: 'running' })
await sdk.status.reportStepStatus(step.id, 'running', { executor: 'custom' })
const output = await runStep(step)
sdk.updateStepState(step.id, { phase: 'completed', output })
await sdk.status.reportStepStatus(step.id, 'completed', {
output,
executor: 'custom',
durationMs: Date.now() - startedMs,
})
}
sdk.updatePhase('completed')
await sdk.status.reportWorkflowStatus('completed', {
completedAt: new Date().toISOString(),
})
emitLog('info', 'Coordinator completed', { workflowName: spec.name })
} catch (err) {
const message = err instanceof Error ? err.message : String(err)
sdk.updatePhase('failed')
await sdk.status.reportWorkflowStatus('failed', { failureReason: message })
emitLog('error', `Coordinator failed: ${message}`)
process.exitCode = 1
} finally {
await sdk.shutdown()
}
}
void main()
Delegating an agentic step to mcp-host
// import { renderPrompt } from '@clerum/workflow-sdk'
// (inside the step loop, with `sdk`, `step`, `spec`, `previousOutputs` in scope)
const mcpHost = sdk.requireMcpHost() // throws McpHostNotConfiguredError if not configured
const result = await mcpHost.executeAgentStep({
stepId: step.id,
instruction: renderPrompt(step.prompt?.template ?? step.instruction ?? '', {
step,
previousOutputs,
workflowName: spec.name,
}),
maxIterations: 8,
timeoutSeconds: 300,
})
if (result.status === 'failed') {
throw new Error(result.error ?? 'agent step failed')
}
Public API reference
| Export | Kind | Purpose |
|---|---|---|
WorkflowSDK |
class | Top-level façade; static fromEnvironment() builds and wires everything. |
WorkflowSDK.fromEnvironment() |
static method | Promise<WorkflowSDK> — the single init call. |
sdk.config (ConfigLoader) |
class | Loads config from env; getConfig(), getSpec(). |
sdk.coordinator (StepCoordinator) |
class | resolveOrder(), injectSignal(), runWorkflow(). |
sdk.status (StatusReporter) |
class | reportStepStatus(), reportWorkflowStatus(), getWorkflowStatus(). |
sdk.signals (SignalPoller) |
class | pollSignals(), pushSignal(), hasSignal(), consumeSignal(), stop(). |
sdk.mcpHost / requireMcpHost() (McpHostClient) |
class | executeAgentStep(), healthCheck(). |
updatePhase() / updateStepState() / shutdown() |
methods | Mirror local REST state; graceful teardown. |
renderPrompt() |
function | Interpolates {{...}} placeholders in a prompt template. |
loadSoul() |
function | Reads a SOUL.md artifact from /etc/workflow/souls (path-traversal guarded). |
requestModelInjection() |
function | POSTs a {stepId, provider, model} model binding to WRC. |
createFileRuntimeTokenProvider() / createStaticRuntimeTokenProvider() / requireRuntimeToken() |
functions | Build / resolve runtime token providers. |
withRetry() / computeBackoff() |
functions | Retry helper and exponential backoff (capped at 300s). |
emitLog() / initLogger() |
functions | Structured JSON logging to stdout. |
createServer() / start() / stop() / safeEqual() |
functions | REST server helpers (health/status/signal routes; constant-time compare). |
WorkflowSDKInitError / CycleDetectedError / McpHostNotConfiguredError |
error classes | Init, DAG-cycle, and unconfigured-mcp-host failures. |
RegistryClient and registry types |
interfaces/types | Registry connection contract (defined in this package). |
| Config/spec types | types | WorkflowConfig, WorkflowRecipeSpec, StepSpec, AgentSpec, ToolScope, PromptSpec, WorkflowPhase, StepPhase, Signal. |
| mcp-host types | types | AgentStepRequest, AgentStepResult, StepMcpServerRef, AllowedToolsConfig. |
| Misc types | types | StepContext, StepExecutor, WorkflowStateRef, RetryOptions, PromptContext, SignalCallback, RuntimeTokenProvider. |
Building a coordinator image
Because @clerum/workflow-sdk re-exports from @clerum/workflow-runtime-core (linked as
file:../workflow-runtime-core), an image that installs or copies only the SDK fails at load
time — both compiled packages must be present under node_modules, and the dependency link
points to a sibling package one directory up. The build context must be the repository root
so both sibling packages resolve.
The multi-stage build below mirrors this package's shipped
Dockerfile.base. --ignore-scripts skips the flaky esbuild/vitest
postinstall lifecycle that the production dist does not need; the base-image stage compiles
with TypeScript only via build:docker.
# Build from the REPOSITORY ROOT: docker build -f coordinator.Dockerfile .
FROM node:24.22.1-alpine AS sdk-builder
WORKDIR /app
# 1) Build runtime-core (the real implementations)
COPY packages/workflow-runtime-core/package.json packages/workflow-runtime-core/package-lock.json ./packages/workflow-runtime-core/
COPY packages/workflow-runtime-core/tsconfig.json ./packages/workflow-runtime-core/
COPY packages/workflow-runtime-core/src ./packages/workflow-runtime-core/src
WORKDIR /app/packages/workflow-runtime-core
RUN npm ci --ignore-scripts && npm run build
# 2) Build the SDK
WORKDIR /app
COPY packages/workflow-sdk/package.json packages/workflow-sdk/package-lock.json ./packages/workflow-sdk/
COPY packages/workflow-sdk/tsconfig.json ./packages/workflow-sdk/
COPY packages/workflow-sdk/src ./packages/workflow-sdk/src
WORKDIR /app/packages/workflow-sdk
RUN npm ci --ignore-scripts && npm run build:docker
# 3) Assemble the runtime image with BOTH packages under node_modules
FROM node:24.22.1-alpine AS base
WORKDIR /app
COPY --from=sdk-builder /app/packages/workflow-runtime-core/dist/ ./node_modules/@clerum/workflow-runtime-core/dist/
COPY packages/workflow-runtime-core/package.json ./node_modules/@clerum/workflow-runtime-core/package.json
COPY --from=sdk-builder /app/packages/workflow-sdk/dist/ ./node_modules/@clerum/workflow-sdk/dist/
COPY packages/workflow-sdk/package.json ./node_modules/@clerum/workflow-sdk/package.json
# 4) Add your compiled coordinator and run as non-root
COPY dist/ ./dist/
RUN mkdir -p /output /tmp && chown -R 1000:1000 /app /output /tmp
USER 1000:1000
ENV NODE_ENV=production
EXPOSE 8090
CMD ["node", "dist/coordinator.js"]
Alternatively, FROM the published clerum-workflow-base image (both packages already present)
and only COPY your own build output.
Image-digest enforcement (on by default)
WRC requires a sha256-digest-pinned spec.coordinatorImage by default
(WRC_REQUIRE_COORDINATOR_IMAGE_DIGEST defaults to true); a tag-only reference is rejected.
Build and ship as if policy is strict:
- Reference images by digest, e.g.
ghcr.io/acme/coordinator@sha256:<64-hex>— no:latest. - Run as user
1000; write only to/tmpand/output. - Do not bundle provider or Clerum credentials; pin third-party dependencies.
(The minikube overlay is the only path that disables enforcement, for local E2E.)
Full guide
For recipe-side configuration see the WorkflowRecipe CRD reference and the WorkflowRecipes operations guide; the gates a custom coordinator image must pass are in Custom coordinator E2E gates.
License
MPL-2.0