@contractspec/integration.workflow-devkit 0.1.1

package/dist/chat-routes.d.ts

@@ -0,0 +1,37 @@
+import type { WorkflowApiLike, WorkflowRunLike } from './types';
+export declare const WORKFLOW_RUN_ID_HEADER = "x-workflow-run-id";
+export declare const WORKFLOW_STREAM_TAIL_INDEX_HEADER = "x-workflow-stream-tail-index";
+export interface CreateWorkflowDevkitStartRouteOptions<TBody = unknown> {
+    buildArgs: (body: TBody, request: Request) => Promise<unknown[]> | unknown[];
+    createResponse?: (params: {
+        body: TBody;
+        run: WorkflowRunLike;
+    }) => Promise<Response> | Response;
+    workflow: (...args: unknown[]) => Promise<unknown>;
+    workflowApi?: Pick<WorkflowApiLike, 'start'>;
+}
+export interface CreateWorkflowDevkitFollowUpRouteOptions<TBody = unknown> {
+    buildPayload?: (body: TBody, request: Request) => Promise<unknown> | unknown;
+    resolveToken: (params: {
+        body: TBody;
+        request: Request;
+        runId: string;
+    }) => string;
+    workflowApi?: Pick<WorkflowApiLike, 'resumeHook'>;
+}
+export interface CreateWorkflowDevkitStreamRouteOptions {
+    workflowApi?: Pick<WorkflowApiLike, 'getRun'>;
+}
+export declare function createWorkflowDevkitStartRoute<TBody = unknown>(options: CreateWorkflowDevkitStartRouteOptions<TBody>): (request: Request) => Promise<Response>;
+export declare function createWorkflowDevkitFollowUpRoute<TBody = unknown>(options: CreateWorkflowDevkitFollowUpRouteOptions<TBody>): (request: Request, context: {
+    params: {
+        id?: string;
+        runId?: string;
+    };
+}) => Promise<Response>;
+export declare function createWorkflowDevkitStreamRoute(options?: CreateWorkflowDevkitStreamRouteOptions): (request: Request, context: {
+    params: {
+        id?: string;
+        runId?: string;
+    };
+}) => Promise<Response>;

package/dist/chat-routes.js

@@ -0,0 +1,101 @@
+// @bun
+// src/chat-routes.ts
+import { createUIMessageStreamResponse } from "ai";
+import { getRun, resumeHook, start } from "workflow/api";
+var WORKFLOW_RUN_ID_HEADER = "x-workflow-run-id";
+var WORKFLOW_STREAM_TAIL_INDEX_HEADER = "x-workflow-stream-tail-index";
+function createWorkflowDevkitStartRoute(options) {
+  const workflowApi = options.workflowApi ?? { start };
+  return async (request) => {
+    const body = await request.json();
+    const args = await options.buildArgs(body, request);
+    const run = await workflowApi.start(options.workflow, args);
+    if (options.createResponse) {
+      return options.createResponse({ body, run });
+    }
+    if (!run.readable) {
+      return new Response(JSON.stringify({ runId: run.runId }), {
+        headers: {
+          "Content-Type": "application/json",
+          [WORKFLOW_RUN_ID_HEADER]: run.runId
+        }
+      });
+    }
+    return createUIMessageStreamResponse({
+      headers: {
+        [WORKFLOW_RUN_ID_HEADER]: run.runId
+      },
+      stream: run.readable
+    });
+  };
+}
+function createWorkflowDevkitFollowUpRoute(options) {
+  const workflowApi = options.workflowApi ?? { resumeHook };
+  return async (request, context) => {
+    const runId = context.params.runId ?? context.params.id;
+    if (!runId) {
+      return new Response(JSON.stringify({ error: "Missing run id" }), {
+        status: 400
+      });
+    }
+    const body = await request.json();
+    const token = options.resolveToken({ body, request, runId });
+    const payload = options.buildPayload ? await options.buildPayload(body, request) : body;
+    await workflowApi.resumeHook(token, payload);
+    return new Response(JSON.stringify({ ok: true }), {
+      headers: {
+        "Content-Type": "application/json",
+        [WORKFLOW_RUN_ID_HEADER]: runId
+      }
+    });
+  };
+}
+function createWorkflowDevkitStreamRoute(options = {}) {
+  const workflowApi = options.workflowApi ?? { getRun };
+  return async (request, context) => {
+    const runId = context.params.runId ?? context.params.id;
+    if (!runId) {
+      return new Response(JSON.stringify({ error: "Missing run id" }), {
+        status: 400
+      });
+    }
+    const run = workflowApi.getRun(runId);
+    if (!run) {
+      return new Response(JSON.stringify({ error: "Workflow run not found" }), {
+        status: 404
+      });
+    }
+    const startIndex = readStartIndex(request.url);
+    const readable = run.getReadable ? run.getReadable({ startIndex }) : run.readable;
+    if (!readable) {
+      return new Response(JSON.stringify({ error: "Run has no readable stream" }), {
+        status: 404
+      });
+    }
+    const tailIndex = await readable.getTailIndex?.();
+    return createUIMessageStreamResponse({
+      headers: {
+        ...tailIndex !== undefined ? {
+          [WORKFLOW_STREAM_TAIL_INDEX_HEADER]: String(tailIndex)
+        } : {}
+      },
+      stream: readable
+    });
+  };
+}
+function readStartIndex(url) {
+  const parsed = new URL(url);
+  const rawStartIndex = parsed.searchParams.get("startIndex");
+  if (!rawStartIndex) {
+    return;
+  }
+  const parsedStartIndex = Number(rawStartIndex);
+  return Number.isFinite(parsedStartIndex) ? parsedStartIndex : undefined;
+}
+export {
+  createWorkflowDevkitStreamRoute,
+  createWorkflowDevkitStartRoute,
+  createWorkflowDevkitFollowUpRoute,
+  WORKFLOW_STREAM_TAIL_INDEX_HEADER,
+  WORKFLOW_RUN_ID_HEADER
+};

package/dist/chat-routes.test.d.ts

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

package/dist/compiler.d.ts

@@ -0,0 +1,9 @@
+import type { WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow';
+import type { WorkflowDevkitCompilation, WorkflowDevkitGeneratedArtifacts } from './types';
+export interface CompileWorkflowSpecToWorkflowDevkitOptions {
+    exportName: string;
+    specImportPath: string;
+    workflowFunctionName?: string;
+}
+export declare function compileWorkflowSpecToWorkflowDevkit(spec: WorkflowSpec): WorkflowDevkitCompilation;
+export declare function generateWorkflowDevkitArtifacts(spec: WorkflowSpec, options: CompileWorkflowSpecToWorkflowDevkitOptions): WorkflowDevkitGeneratedArtifacts;

package/dist/compiler.js

@@ -0,0 +1,178 @@
+// @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/compiler.ts
+function compileWorkflowSpecToWorkflowDevkit(spec) {
+  return {
+    entryStepId: resolveWorkflowDevkitEntryStepId(spec),
+    hostTarget: spec.runtime?.workflowDevkit?.hostTarget ?? "generic",
+    hookTokenStrategy: spec.runtime?.workflowDevkit?.hookTokens?.strategy ?? "deterministic",
+    integrationMode: spec.runtime?.workflowDevkit?.integrationMode ?? "manual",
+    runIdentityStrategy: spec.runtime?.workflowDevkit?.runIdentity?.strategy ?? "meta-key-version",
+    specKey: spec.meta.key,
+    specVersion: spec.meta.version,
+    steps: spec.definition.steps.map((step) => ({
+      behavior: inferWorkflowDevkitBehavior(step),
+      id: step.id,
+      label: step.label,
+      operationRef: step.action?.operation ? `${step.action.operation.key}.v${step.action.operation.version}` : undefined,
+      runtime: step.runtime?.workflowDevkit,
+      transitions: spec.definition.transitions.filter((transition) => transition.from === step.id).map((transition) => ({
+        condition: transition.condition,
+        to: transition.to
+      })),
+      type: step.type,
+      waitToken: resolveWorkflowDevkitWaitToken(spec, step)
+    }))
+  };
+}
+function generateWorkflowDevkitArtifacts(spec, options) {
+  const compilation = compileWorkflowSpecToWorkflowDevkit(spec);
+  const workflowFunctionName = options.workflowFunctionName ?? `${sanitizeIdentifier(options.exportName)}WorkflowDevkit`;
+  return {
+    genericBootstrap: createGenericBootstrapTemplate(options.exportName, workflowFunctionName),
+    manifest: JSON.stringify(compilation, null, 2),
+    nextFollowUpRoute: createFollowUpRouteTemplate(workflowFunctionName),
+    nextStartRoute: createStartRouteTemplate(workflowFunctionName),
+    nextStreamRoute: createStreamRouteTemplate(),
+    workflowModule: createWorkflowModuleTemplate(options.exportName, options.specImportPath, workflowFunctionName)
+  };
+}
+function createGenericBootstrapTemplate(exportName, workflowFunctionName) {
+  return `import { ${workflowFunctionName} } from "./${sanitizeIdentifier(exportName)}.workflow-devkit";
+
+export const ${sanitizeIdentifier(exportName)}WorkflowDevkitBootstrap = {
+  workflow: ${workflowFunctionName},
+  createBridge() {
+    return {
+      executeAutomationStep: async () => {
+        throw new Error("Provide executeAutomationStep in your generic host bridge.");
+      },
+    };
+  },
+};
+`;
+}
+function createStartRouteTemplate(workflowFunctionName) {
+  return `import { createWorkflowDevkitStartRoute } from "@contractspec/integration.workflow-devkit";
+import { ${workflowFunctionName} } from "./workflow";
+
+export const POST = createWorkflowDevkitStartRoute({
+  workflow: ${workflowFunctionName},
+  async buildArgs(body) {
+    return [body];
+  },
+});
+`;
+}
+function createFollowUpRouteTemplate(workflowFunctionName) {
+  return `import { createWorkflowDevkitFollowUpRoute } from "@contractspec/integration.workflow-devkit";
+
+export const POST = createWorkflowDevkitFollowUpRoute({
+  resolveToken({ runId }) {
+    return \`${workflowFunctionName}:\${runId}\`;
+  },
+});
+`;
+}
+function createStreamRouteTemplate() {
+  return `import { createWorkflowDevkitStreamRoute } from "@contractspec/integration.workflow-devkit";
+
+export const GET = createWorkflowDevkitStreamRoute();
+`;
+}
+function createWorkflowModuleTemplate(exportName, specImportPath, workflowFunctionName) {
+  return `import { createHook, createWebhook, sleep } from "workflow";
+import { runWorkflowSpecWithWorkflowDevkit } from "@contractspec/integration.workflow-devkit";
+import { ${exportName} } from "${specImportPath}";
+
+export async function ${workflowFunctionName}(input = {}, bridge = {}) {
+  "use workflow";
+
+  return runWorkflowSpecWithWorkflowDevkit({
+    spec: ${exportName},
+    initialData: input,
+    bridge,
+    primitives: {
+      sleep,
+      createHook,
+      createWebhook,
+    },
+  });
+}
+`;
+}
+export {
+  generateWorkflowDevkitArtifacts,
+  compileWorkflowSpecToWorkflowDevkit
+};

package/dist/compiler.test.d.ts

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

package/dist/helpers.d.ts

@@ -0,0 +1,8 @@
+import type { Step, WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow';
+export declare function inferWorkflowDevkitBehavior(step: Step): import("@contractspec/lib.contracts-spec/workflow").StepType | import("@contractspec/lib.contracts-spec/workflow").WorkflowDevkitStepBehavior;
+export declare function resolveWorkflowDevkitEntryStepId(spec: WorkflowSpec): string;
+export declare function resolveWorkflowDevkitRunIdentity(spec: WorkflowSpec, runIdentity?: string): string;
+export declare function resolveWorkflowDevkitWaitToken(spec: WorkflowSpec, step: Step, runIdentity?: string): string | undefined;
+export declare function resolveWorkflowDevkitNextStepId(spec: WorkflowSpec, step: Step, data: Record<string, unknown>, input?: unknown, output?: unknown): string | null;
+export declare function mergeWorkflowDevkitData(current: Record<string, unknown>, input?: unknown, output?: unknown): Record<string, unknown>;
+export declare function sanitizeIdentifier(value: string): string;

package/dist/helpers.js

@@ -0,0 +1,81 @@
+// @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);
+}
+export {
+  sanitizeIdentifier,
+  resolveWorkflowDevkitWaitToken,
+  resolveWorkflowDevkitRunIdentity,
+  resolveWorkflowDevkitNextStepId,
+  resolveWorkflowDevkitEntryStepId,
+  mergeWorkflowDevkitData,
+  inferWorkflowDevkitBehavior
+};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { WorkflowChatTransport } from '@workflow/ai';
+export { createWorkflowDevkitAgentRuntimeAdapterBundle, defaultWorkflowDevkitAgentToken, InMemoryWorkflowDevkitCheckpointStore, InMemoryWorkflowDevkitSuspensionStore, } from './agent-adapter';
+export { createWorkflowDevkitFollowUpRoute, createWorkflowDevkitStartRoute, createWorkflowDevkitStreamRoute, WORKFLOW_RUN_ID_HEADER, WORKFLOW_STREAM_TAIL_INDEX_HEADER, } from './chat-routes';
+export { compileWorkflowSpecToWorkflowDevkit, generateWorkflowDevkitArtifacts, } from './compiler';
+export * from './helpers';
+export { withContractSpecWorkflow } from './next';
+export { runWorkflowSpecWithWorkflowDevkit } from './runtime';
+export type * from './types';