World engine (workflows durables)

import { WorkflowKit } from "@ai_kit/core";

const kit = new WorkflowKit({
  engine: "legacy", // défaut — peut être omis
});

// Legacy: workflow = un Workflow AI Kit, input = WorkflowRunOptions
const result = await kit.run(myLegacyWorkflow, { inputData: { id: 42 } });
console.log(result.status); // "success" | "failed" | ...

const kit = new WorkflowKit({
  engine: "world",
  world: { type: "postgres", url: process.env.WORKFLOW_POSTGRES_URL! },
});

await kit.start();                                  // démarre le worker durable
const handle = await kit.run(handleUserSignup, ["hello@example.com"]);
console.log(handle.runId);
await kit.stop();                                   // arrêt propre

interface WorkflowKitOptions {
  engine?: "legacy" | "world"; // défaut "legacy"
  world?: WorldConfig;         // requis quand engine === "world"
}

interface WorldConfig {
  type: "postgres" | "mongodb";
  url: string;                 // chaîne de connexion
  jobPrefix?: string;          // postgres: espace de noms des jobs sur une DB partagée
  workerConcurrency?: number;  // postgres: workers concurrents
  maxPoolSize?: number;        // postgres: taille du pool de connexions
}

const report = await kit.runAndWait(reportWorkflow, [input]); // se résout avec la sortie

const run = await kit.run(reportWorkflow, [input]);
const report = await run.returnValue;     // lève une erreur si le run a échoué / été annulé
console.log(run.runId, await run.status); // aussi : run.exists, run.cancel()

pnpm add @ai_kit/core @ai_kit/workflow-world workflow
# choisissez le backend world dont vous avez besoin (peer dependency optionnelle) :
pnpm add @workflow/world-postgres            # Postgres (officiel)
# ou
pnpm add @workflow-worlds/mongodb            # MongoDB (communauté, expérimental)
# build de l'application hôte :
pnpm add -D nitro rollup

import { sleep, FatalError } from "workflow";

export async function handleUserSignup(email: string) {
  "use workflow";                       // le corps doit être déterministe
  const user = await createUser(email); // chaque await est un checkpoint durable
  await sendWelcomeEmail(user);
  await sleep("5s");
  return { userId: user.id };
}

async function createUser(email: string) {
  "use step";                           // runtime Node complet, ré-essayé automatiquement
  if (!email.includes("@")) throw new FatalError("invalid email");
  return { id: crypto.randomUUID(), email };
}

async function sendWelcomeEmail(user: { id: string; email: string }) {
  "use step";
  return { sent: true };
}

import type { WorldStep } from "@ai_kit/workflow-world";

// une flèche liée directement à un const est également détectée par le compilateur
export const charge: WorldStep<[Order], Receipt> = async (order) => {
  "use step";
  return chargePayment(order);
};

WORKFLOW_POSTGRES_URL=postgres://world:world@localhost:5432/world npx workflow-postgres-setup

const kit = new WorkflowKit({
  engine: "world",
  world: { type: "mongodb", url: process.env.WORKFLOW_MONGODB_URI! },
});
await kit.start();

// nitro.config.ts (application hôte)
import { defineNitroConfig } from "nitro/config";

export default defineNitroConfig({
  modules: ["workflow/nitro"],
  routes: { "/**": { handler: "./src/index.ts", format: "node" } },
});

import { createWorkflow, createStep } from "@ai_kit/core";

const fetchOrder = createStep({ id: "fetchOrder", handler: async ({ inputData }) => getOrder(inputData.id) });
const charge = createStep({ id: "charge", handler: async ({ inputData }) => chargePayment(inputData) });

export const orderWorkflow = createWorkflow({ id: "order" })
  .then(fetchOrder)
  .then(charge)
  .commit();

await orderWorkflow.run({ inputData: { id: "o_123" } });

export async function orderWorkflow(orderId: string) {
  "use workflow";
  const order = await fetchOrder(orderId);
  const charged = await charge(order);
  return { orderId, status: "completed" };
}

async function fetchOrder(id: string) { "use step"; return getOrder(id); }
async function charge(order: Order)   { "use step"; return chargePayment(order); }

// lancé via la façade
await kit.run(orderWorkflow, ["o_123"]);