Skip to content
ContractSpec
Start here

Package manual · integrations

·Workflows, jobs and automation

integration.workflow-devkit

Workflow DevKit compiler and runtime bridges for ContractSpec workflows

integrationsintegrationv2.0.6experimentalservernode
@lssm-tech/integration.workflow-devkit
bun add @lssm-tech/integration.workflow-devkit
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Workflow DevKit compiler and runtime bridges for ContractSpec WorkflowSpec.

What it provides

  • Compile a WorkflowSpec into a deterministic Workflow DevKit manifest.
  • Generate Workflow, Next.js, and generic-host scaffolding.
  • Run a WorkflowSpec through injected Workflow DevKit primitives such as sleep, hooks, and webhooks.
  • Create a Workflow-backed AgentRuntimeAdapterBundle for @lssm-tech/lib.ai-agent.
  • Expose chat route helpers and re-export WorkflowChatTransport for reconnectable chat UIs.

Entry points

  • @lssm-tech/integration.workflow-devkit
  • @lssm-tech/integration.workflow-devkit/compiler
  • @lssm-tech/integration.workflow-devkit/runtime
  • @lssm-tech/integration.workflow-devkit/chat-routes
  • @lssm-tech/integration.workflow-devkit/agent-adapter
  • @lssm-tech/integration.workflow-devkit/next

Workflow vs step boundary

Workflow DevKit code runs across two different execution contexts:

  • Workflow functions ("use workflow") orchestrate control flow and must stay deterministic.
  • Step functions ("use step") perform the actual Node.js work.

This matches the Workflow docs: workflow functions do not have full Node.js access, while step functions do. Keep Node.js core modules, SDK clients, database access, and other side effects inside use step helpers. The workflow function itself should only compose Workflow primitives and call step helpers.

For WorkflowSpec authoring in Workflow-hosted apps, import the safe authoring API from @lssm-tech/lib.contracts-spec/workflow/spec, not the broad @lssm-tech/lib.contracts-spec/workflow barrel.

Next.js example

ts
import { withContractSpecWorkflow } from "@lssm-tech/integration.workflow-devkit/next";
import { createWorkflowChatRoutes } from "@lssm-tech/module.ai-chat/core/workflow";

export default withContractSpecWorkflow({
  experimental: {},
});

const routes = createWorkflowChatRoutes({
  workflow: async (payload) => payload,
  getFollowUpToken({ runId }) {
    return `chat:${runId}`;
  },
});

export const POST = routes.start;

Generic host example

ts
import { createHook, createWebhook, sleep } from "workflow";
import {
  runWorkflowSpecWithWorkflowDevkit,
  type WorkflowDevkitRuntimeBridge,
} from "@lssm-tech/integration.workflow-devkit";
import { onboardingWorkflow } from "./onboarding.workflow";

export async function runOnboarding(input: Record<string, unknown>, bridge: WorkflowDevkitRuntimeBridge) {
  "use workflow";

  // Keep this function deterministic. Node.js work belongs in `use step`
  // helpers that your bridge dispatches to.
  return runWorkflowSpecWithWorkflowDevkit({
    spec: onboardingWorkflow,
    initialData: input,
    bridge,
    primitives: {
      sleep,
      createHook,
      createWebhook,
    },
  });
}

Relationships

THIS PACKAGEintegration.workflow-devkit10 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

8 declarations

Declared capabilities

Integration Workflow Devkit

Workflow DevKit compiler and runtime bridges for ContractSpec workflows

Scripts

  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • publish:pkg:canarybun publish:pkg --tag canary
  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lintbun lint:fix
  • lint:fixnode ../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .
  • lint:checknode ../../../scripts/biome.cjs check .
  • testbun test
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit