@workflow-studio/core

Overview

@workflow-studio/core contains the shared pieces that both app code and the worker rely on.

It includes:

ComputeClient for calling the worker over HTTP
request and response schemas
worker error schemas
config loading helpers
framework integration helpers
the remote world implementation used by workflow-studio/world-remote

`ComputeClient`

Use ComputeClient when you need to call the worker directly from automation, tests, or app-side integrations.

client.ts

import { ComputeClient } from '@workflow-studio/core';

const client = new ComputeClient({
  baseUrl: 'https://worker.example.com',
  apiKey: process.env.WORKFLOW_COMPUTE_API_KEY,
  timeoutMs: 10_000,
  retries: 2,
});

Run methods

trigger(request, { idempotencyKey? })
getRun(runId)
cancelRun(runId)
resumeRun(request)
rerunRun(runId, request?)
wakeRun(runId, request?)

Observability methods

listRunTimeline(runId)
listEventsByCorrelationId(correlationId)
listRunSteps(runId)
listRunHooks(runId)
getRunStep(stepId)
getRunHook(hookId)

Deployment methods

createDeployment(manifest, artifact, contentType?)
activateDeployment(deploymentId)
rollbackDeployment(deploymentId)
getDeployment(deploymentId)
getActiveDeployment()

Error responses

Worker errors use a structured JSON response body with:

code
message
optional required
optional recovery

Common error codes include:

unauthorized
missing_scope
rate_limited
idempotency_required
idempotency_conflict
no_active_deployment
invalid_manifest
invalid_deployment_id
https_required
not_found

Idempotency

POST /v1/runs requires an Idempotency-Key header.

When you call trigger, provide a stable idempotency key for retried requests so the worker can safely replay the accepted response instead of creating duplicate runs.

Config helpers

@workflow-studio/core also loads and normalizes Workflow Studio config.

Key helpers include:

loadWorkflowStudioConfig
getServerEnvDefaults
resolveWorkflowStudioAdapterConfig
shouldExecuteRemotely

Framework helpers

These helpers are exported from @workflow-studio/core and re-exposed through workflow-studio package entrypoints:

withWorkflowStudioNext
withWorkflowStudioNitro
withWorkflowStudioSvelteKit
proxyTriggerFromNext
proxyTriggerFromNitro
proxyTriggerFromSvelteKit
proxyWebhookFromNext
proxyWebhookFromNitro
proxyWebhookFromSvelteKit

Contracts and schemas

The shared schema layer includes:

deployment IDs and run IDs
API key scopes
trigger, resume, wake, and deployment request shapes
paginated run, step, hook, and event response shapes
worker error codes

Current worker scopes are:

Scope	Use
`trigger:write`	trigger runs
`runs:read`	read runs, steps, hooks, and events
`runs:write`	cancel, resume, rerun, and wake
`deploy:read`	read deployments
`deploy:write`	create and activate deployments
`world:proxy`	internal world transport routes
`admin`	full access

See API Keys and Scopes for route-level guidance.

Remote world integration

@workflow-studio/core provides the remote world implementation used when the app runs with:

WORKFLOW_TARGET_WORLD=workflow-studio/world-remote

This keeps existing workflow imports unchanged while routing execution and state operations to the worker.

On this page