@contractspec/integration.workflow-devkit 0.1.1

package/dist/runtime.js

@@ -0,0 +1,181 @@
+// @bun
+// src/helpers.ts
+import { evaluateExpression } from "@contractspec/lib.contracts-spec/workflow";
+function inferWorkflowDevkitBehavior(step) {
+  return step.runtime?.workflowDevkit?.behavior ?? step.type;
+}
+function resolveWorkflowDevkitEntryStepId(spec) {
+  const entryStepId = spec.definition.entryStepId ?? spec.definition.steps[0]?.id;
+  if (!entryStepId) {
+    throw new Error(`Workflow ${spec.meta.key}.v${spec.meta.version} does not define an entry step.`);
+  }
+  return entryStepId;
+}
+function resolveWorkflowDevkitRunIdentity(spec, runIdentity) {
+  if (runIdentity) {
+    return runIdentity;
+  }
+  const strategy = spec.runtime?.workflowDevkit?.runIdentity?.strategy ?? "meta-key-version";
+  const prefix = spec.runtime?.workflowDevkit?.runIdentity?.prefix;
+  const baseIdentity = strategy === "meta-key-version" ? `${spec.meta.key}.v${spec.meta.version}` : `${spec.meta.key}.v${spec.meta.version}`;
+  return prefix ? `${prefix}:${baseIdentity}` : baseIdentity;
+}
+function resolveWorkflowDevkitWaitToken(spec, step, runIdentity) {
+  const runtime = step.runtime?.workflowDevkit;
+  if (!runtime) {
+    return;
+  }
+  const explicitToken = runtime.hookWait?.token ?? runtime.webhookWait?.token ?? runtime.approvalWait?.token ?? runtime.streamSession?.followUpToken;
+  if (explicitToken) {
+    return explicitToken;
+  }
+  const tokenStrategy = spec.runtime?.workflowDevkit?.hookTokens?.strategy ?? "deterministic";
+  const prefix = spec.runtime?.workflowDevkit?.hookTokens?.prefix ?? spec.meta.key;
+  const stableStepId = sanitizeIdentifier(step.id);
+  if (tokenStrategy === "session-scoped") {
+    const resolvedRunIdentity = sanitizeIdentifier(resolveWorkflowDevkitRunIdentity(spec, runIdentity));
+    return `${prefix}:${resolvedRunIdentity}:${stableStepId}`;
+  }
+  if (tokenStrategy === "step-scoped") {
+    return `${prefix}:v${spec.meta.version}:${stableStepId}`;
+  }
+  return `${prefix}:${stableStepId}`;
+}
+function resolveWorkflowDevkitNextStepId(spec, step, data, input, output) {
+  const transitions = spec.definition.transitions.filter((transition) => transition.from === step.id);
+  for (const transition of transitions) {
+    if (evaluateExpression(transition.condition, {
+      data,
+      input,
+      output
+    })) {
+      return transition.to;
+    }
+  }
+  return null;
+}
+function mergeWorkflowDevkitData(current, input, output) {
+  const next = { ...current };
+  if (isRecord(input)) {
+    Object.assign(next, input);
+  }
+  if (isRecord(output)) {
+    Object.assign(next, output);
+  }
+  return next;
+}
+function sanitizeIdentifier(value) {
+  return value.replace(/[^a-zA-Z0-9_-]+/g, "-");
+}
+function isRecord(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+// src/runtime.ts
+async function runWorkflowSpecWithWorkflowDevkit(options) {
+  const history = [];
+  let currentStepId = resolveWorkflowDevkitEntryStepId(options.spec);
+  let data = { ...options.initialData ?? {} };
+  let input = options.initialData;
+  while (currentStepId) {
+    const step = lookupStep(options.spec, currentStepId);
+    const runtime = step.runtime?.workflowDevkit;
+    const context = {
+      data,
+      input,
+      runIdentity: options.runIdentity,
+      runtime,
+      spec: options.spec,
+      step
+    };
+    const behavior = inferWorkflowDevkitBehavior(step);
+    const token = resolveWorkflowDevkitWaitToken(options.spec, step, options.runIdentity);
+    const output = await executeWorkflowDevkitBehavior(behavior, context, token, options.bridge, options.primitives);
+    history.push({
+      behavior,
+      input,
+      output,
+      stepId: step.id,
+      token
+    });
+    data = mergeWorkflowDevkitData(data, input, output);
+    const nextStepId = resolveWorkflowDevkitNextStepId(options.spec, step, data, input, output);
+    if (!nextStepId) {
+      return {
+        currentStep: null,
+        data,
+        history,
+        status: "completed"
+      };
+    }
+    currentStepId = nextStepId;
+    input = output;
+  }
+  return {
+    currentStep: null,
+    data,
+    history,
+    status: "completed"
+  };
+}
+async function executeWorkflowDevkitBehavior(behavior, context, token, bridge, primitives) {
+  switch (behavior) {
+    case "sleep":
+      if (!context.runtime?.sleep?.duration) {
+        throw new Error(`Step "${context.step.id}" is missing sleep.duration.`);
+      }
+      await primitives.sleep(context.runtime.sleep.duration);
+      return { sleptFor: context.runtime.sleep.duration };
+    case "hookWait":
+      return awaitExternalWait(context, token, bridge?.onExternalWait, primitives.createHook);
+    case "webhookWait":
+      return awaitExternalWait(context, token, bridge?.onExternalWait, primitives.createWebhook ?? primitives.createHook, context.runtime?.webhookWait?.path, context.runtime?.webhookWait?.method);
+    case "approvalWait":
+      return awaitExternalWait(context, token, bridge?.onApprovalRequested, primitives.createHook);
+    case "streamSession":
+      return awaitExternalWait(context, token, bridge?.onStreamSession, primitives.createHook);
+    case "automation":
+      if (!bridge?.executeAutomationStep) {
+        throw new Error("Workflow DevKit bridge requires executeAutomationStep for automation steps.");
+      }
+      return bridge.executeAutomationStep(context);
+    case "human":
+      if (!bridge?.awaitHumanInput) {
+        throw new Error("Workflow DevKit bridge requires awaitHumanInput for human steps without explicit wait behavior.");
+      }
+      return bridge.awaitHumanInput(context);
+    case "decision":
+      return bridge?.executeDecisionStep ? bridge.executeDecisionStep(context) : context.input;
+  }
+}
+async function awaitExternalWait(context, token, notifier, factory, path, method) {
+  if (!token) {
+    throw new Error(`Step "${context.step.id}" requires a Workflow DevKit wait token.`);
+  }
+  const behavior = context.runtime?.behavior;
+  if (behavior !== "approvalWait" && behavior !== "hookWait" && behavior !== "streamSession" && behavior !== "webhookWait") {
+    throw new Error(`Step "${context.step.id}" is not configured with an external wait behavior.`);
+  }
+  const waitContext = {
+    ...context,
+    behavior,
+    token
+  };
+  await notifier?.(waitContext);
+  const hook = factory({ method, path, token });
+  try {
+    return await hook;
+  } finally {
+    await hook.dispose?.();
+  }
+}
+function lookupStep(spec, stepId) {
+  const step = spec.definition.steps.find((candidate) => candidate.id === stepId);
+  if (!step) {
+    throw new Error(`Step "${stepId}" not found in workflow ${spec.meta.key}.v${spec.meta.version}.`);
+  }
+  return step;
+}
+export {
+  runWorkflowSpecWithWorkflowDevkit
+};

package/dist/runtime.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,97 @@
+import type { Step, WorkflowDevkitHostTarget, WorkflowDevkitIntegrationMode, WorkflowDevkitStepBehavior, WorkflowDevkitStepRuntimeConfig, WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow';
+import type { UIMessageChunk } from 'ai';
+export interface WorkflowDevkitCompiledTransition {
+    condition?: string;
+    to: string;
+}
+export interface WorkflowDevkitCompiledStep {
+    behavior: Step['type'] | WorkflowDevkitStepBehavior;
+    id: string;
+    label: string;
+    operationRef?: string;
+    runtime?: WorkflowDevkitStepRuntimeConfig;
+    transitions: WorkflowDevkitCompiledTransition[];
+    type: Step['type'];
+    waitToken?: string;
+}
+export interface WorkflowDevkitCompilation {
+    entryStepId: string;
+    hostTarget: WorkflowDevkitHostTarget;
+    hookTokenStrategy: string;
+    integrationMode: WorkflowDevkitIntegrationMode;
+    runIdentityStrategy: string;
+    specKey: string;
+    specVersion: string;
+    steps: WorkflowDevkitCompiledStep[];
+}
+export interface WorkflowDevkitGeneratedArtifacts {
+    genericBootstrap: string;
+    manifest: string;
+    nextFollowUpRoute: string;
+    nextStartRoute: string;
+    nextStreamRoute: string;
+    workflowModule: string;
+}
+export interface WorkflowDevkitRuntimeStepContext {
+    data: Record<string, unknown>;
+    input?: unknown;
+    runIdentity?: string;
+    runtime?: WorkflowDevkitStepRuntimeConfig;
+    spec: WorkflowSpec;
+    step: Step;
+}
+export interface WorkflowDevkitExternalWaitContext extends WorkflowDevkitRuntimeStepContext {
+    behavior: WorkflowDevkitStepBehavior;
+    token: string;
+}
+export interface WorkflowDevkitRuntimeBridge {
+    awaitHumanInput?: (context: WorkflowDevkitRuntimeStepContext) => Promise<unknown>;
+    executeAutomationStep?: (context: WorkflowDevkitRuntimeStepContext) => Promise<unknown>;
+    executeDecisionStep?: (context: WorkflowDevkitRuntimeStepContext) => Promise<unknown>;
+    onApprovalRequested?: (context: WorkflowDevkitExternalWaitContext) => Promise<void> | void;
+    onExternalWait?: (context: WorkflowDevkitExternalWaitContext) => Promise<void> | void;
+    onStreamSession?: (context: WorkflowDevkitExternalWaitContext) => Promise<void> | void;
+}
+export interface WorkflowDevkitHookLike<T = unknown> extends AsyncIterable<T>, PromiseLike<T> {
+    dispose?: () => Promise<void> | void;
+    token: string;
+}
+export interface WorkflowDevkitPrimitives {
+    createHook: <T = unknown>(options?: {
+        token?: string;
+    }) => WorkflowDevkitHookLike<T>;
+    createWebhook?: <T = unknown>(options?: {
+        method?: string;
+        path?: string;
+        token?: string;
+    }) => WorkflowDevkitHookLike<T>;
+    sleep: (duration: string) => Promise<void>;
+}
+export interface WorkflowDevkitExecutionRecord {
+    behavior: Step['type'] | WorkflowDevkitStepBehavior;
+    input?: unknown;
+    output?: unknown;
+    stepId: string;
+    token?: string;
+}
+export interface WorkflowDevkitRunResult {
+    currentStep: string | null;
+    data: Record<string, unknown>;
+    history: WorkflowDevkitExecutionRecord[];
+    status: 'completed';
+}
+export interface WorkflowRunReadableLike extends ReadableStream<UIMessageChunk> {
+    getTailIndex?: () => number | Promise<number>;
+}
+export interface WorkflowRunLike {
+    getReadable?: (options?: {
+        startIndex?: number;
+    }) => WorkflowRunReadableLike;
+    readable?: WorkflowRunReadableLike;
+    runId: string;
+}
+export interface WorkflowApiLike {
+    getRun: (runId: string) => WorkflowRunLike | null | undefined;
+    resumeHook: (token: string, payload: unknown) => Promise<unknown>;
+    start: (workflow: (...args: unknown[]) => Promise<unknown>, args: unknown[]) => Promise<WorkflowRunLike>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+// @bun

package/package.json

@@ -0,0 +1,173 @@
+{
+  "name": "@contractspec/integration.workflow-devkit",
+  "version": "0.1.1",
+  "description": "Workflow DevKit compiler and runtime bridges for ContractSpec workflows",
+  "keywords": [
+    "contractspec",
+    "workflow",
+    "workflow-devkit",
+    "durable",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/browser/index.js",
+      "bun": "./dist/index.js",
+      "node": "./dist/node/index.js",
+      "default": "./dist/index.js"
+    },
+    "./agent-adapter": {
+      "types": "./dist/agent-adapter.d.ts",
+      "browser": "./dist/browser/agent-adapter.js",
+      "bun": "./dist/agent-adapter.js",
+      "node": "./dist/node/agent-adapter.js",
+      "default": "./dist/agent-adapter.js"
+    },
+    "./chat-routes": {
+      "types": "./dist/chat-routes.d.ts",
+      "browser": "./dist/browser/chat-routes.js",
+      "bun": "./dist/chat-routes.js",
+      "node": "./dist/node/chat-routes.js",
+      "default": "./dist/chat-routes.js"
+    },
+    "./compiler": {
+      "types": "./dist/compiler.d.ts",
+      "browser": "./dist/browser/compiler.js",
+      "bun": "./dist/compiler.js",
+      "node": "./dist/node/compiler.js",
+      "default": "./dist/compiler.js"
+    },
+    "./helpers": {
+      "types": "./dist/helpers.d.ts",
+      "browser": "./dist/browser/helpers.js",
+      "bun": "./dist/helpers.js",
+      "node": "./dist/node/helpers.js",
+      "default": "./dist/helpers.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "browser": "./dist/browser/next.js",
+      "bun": "./dist/next.js",
+      "node": "./dist/node/next.js",
+      "default": "./dist/next.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "browser": "./dist/browser/runtime.js",
+      "bun": "./dist/runtime.js",
+      "node": "./dist/node/runtime.js",
+      "default": "./dist/runtime.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "browser": "./dist/browser/types.js",
+      "bun": "./dist/types.js",
+      "node": "./dist/node/types.js",
+      "default": "./dist/types.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun run prebuild && bun run build:bundle && bun run build:types",
+    "build:bundle": "contractspec-bun-build transpile",
+    "build:types": "contractspec-bun-build types",
+    "dev": "contractspec-bun-build dev",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .",
+    "lint:check": "biome check .",
+    "test": "bun test",
+    "prebuild": "contractspec-bun-build prebuild",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@contractspec/lib.ai-agent": "8.0.3",
+    "@contractspec/lib.contracts-spec": "5.0.3",
+    "@workflow/ai": "^4.1.0-beta.58",
+    "ai": "6.0.138",
+    "workflow": "^4.2.0-beta.72"
+  },
+  "devDependencies": {
+    "@contractspec/tool.bun": "3.7.11",
+    "@contractspec/tool.typescript": "3.7.11",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "browser": "./dist/browser/index.js",
+        "bun": "./dist/index.js",
+        "node": "./dist/node/index.js",
+        "default": "./dist/index.js"
+      },
+      "./agent-adapter": {
+        "types": "./dist/agent-adapter.d.ts",
+        "browser": "./dist/browser/agent-adapter.js",
+        "bun": "./dist/agent-adapter.js",
+        "node": "./dist/node/agent-adapter.js",
+        "default": "./dist/agent-adapter.js"
+      },
+      "./chat-routes": {
+        "types": "./dist/chat-routes.d.ts",
+        "browser": "./dist/browser/chat-routes.js",
+        "bun": "./dist/chat-routes.js",
+        "node": "./dist/node/chat-routes.js",
+        "default": "./dist/chat-routes.js"
+      },
+      "./compiler": {
+        "types": "./dist/compiler.d.ts",
+        "browser": "./dist/browser/compiler.js",
+        "bun": "./dist/compiler.js",
+        "node": "./dist/node/compiler.js",
+        "default": "./dist/compiler.js"
+      },
+      "./helpers": {
+        "types": "./dist/helpers.d.ts",
+        "browser": "./dist/browser/helpers.js",
+        "bun": "./dist/helpers.js",
+        "node": "./dist/node/helpers.js",
+        "default": "./dist/helpers.js"
+      },
+      "./next": {
+        "types": "./dist/next.d.ts",
+        "browser": "./dist/browser/next.js",
+        "bun": "./dist/next.js",
+        "node": "./dist/node/next.js",
+        "default": "./dist/next.js"
+      },
+      "./runtime": {
+        "types": "./dist/runtime.d.ts",
+        "browser": "./dist/browser/runtime.js",
+        "bun": "./dist/runtime.js",
+        "node": "./dist/node/runtime.js",
+        "default": "./dist/runtime.js"
+      },
+      "./types": {
+        "types": "./dist/types.d.ts",
+        "browser": "./dist/browser/types.js",
+        "bun": "./dist/types.js",
+        "node": "./dist/node/types.js",
+        "default": "./dist/types.js"
+      }
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/integrations/workflow-devkit"
+  },
+  "homepage": "https://contractspec.io"
+}