Build a durable workflow

workflows:
  driver: db                                           # the journal lives in your database
  retries: { max: 3, backoff: exponential, initial: 1s }   # the default for each step

workflows:
  driver: local        # in process, for development and tests

import { approve, sleep, step, waitFor, workflow } from "mainsdk/workflows";
import { s } from "mainsdk/schema";

// Your own code. Steps return JSON, so return ids and small values.
async function loadUser(userId: string) { return { id: userId, email: `${userId}@pinecart.dev` }; }
async function sendWelcome(email: string) { console.log("welcome sent to", email); return { sent: true }; }
async function grantCredits(userId: string, amount: number) { console.log("granted", amount, "to", userId); return { granted: amount }; }

export const onboarding = workflow(
  "onboarding",
  { version: 1, input: s.object({ userId: s.string() }) },
  async ({ userId }) => {
    const user = await step("load-user", () => loadUser(userId));
    await step("welcome", () => sendWelcome(user.email));
    await sleep("3d");                                            // parks the run; holds no worker
    const activated = await waitFor("user.activated", { match: { userId }, timeout: "7d" });
    if (!activated) return { activated: false };
    const ok = await approve({ action: "credits.grant", risk: "write", spend: "$5", reason: "Welcome credits", timeout: "2d" });
    if (ok.approved) await step("grant", () => grantCredits(userId, 5), { retries: { max: 2 } });
    return { activated: true, granted: ok.approved };
  },
);

import { workflows, type WorkflowDef } from "mainsdk/workflows";

declare const onboarding: WorkflowDef<{ userId: string }>;   // exported from app/workflows/onboarding.ts

const { runId } = await workflows.start(onboarding, { userId: "u_1" }, { idempotencyKey: "onboarding:u_1" });

import { workflows } from "mainsdk/workflows";

declare const runId: string;                                    // from workflows.start()

const run = await workflows.get(runId);
console.log(run.state, run.currentStep, run.history.map((h) => `${h.step}:${h.kind}`));

import { events } from "mainsdk";

await events.publish("user.activated", { userId: "u_1" });

import { agents } from "mainsdk";

declare const session: { user: { id: string } };                // the signed-in approver

const [pending] = agents.pendingApprovals();                    // what is waiting, with its reason and spend
agents.approve(pending.id, { kind: "user", id: session.user.id });

import { workflows } from "mainsdk/workflows";

declare const runId: string;                                    // from workflows.start()

const waiting = await workflows.list({ name: "onboarding", state: "waiting" });
await workflows.cancel(runId, { reason: "user closed the account" });

import { workflow } from "mainsdk/workflows";

export const onboardingV2 = workflow("onboarding", { version: 2 /* , input, and the new steps */ }, async () => {
  /* the new steps */
});

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";
import type { WorkflowDef } from "mainsdk/workflows";

declare const onboarding: WorkflowDef<{ userId: string }>;      // exported from app/workflows/onboarding.ts

describe("onboarding workflow", () => {
  it("workflows AC1 runs each step once, sleeps, waits, asks for approval and finishes", async () => {
    const app = createTestApp();
    const { runId } = await app.workflows.start(onboarding, { userId: "u_1" }, { idempotencyKey: "onboarding:u_1" });
    await app.clock.tick("1m");
    assert.equal((await app.workflows.get(runId)).state, "sleeping");

    await app.clock.tick("3d");                       // the sleep ends; now it waits for the event
    assert.equal((await app.workflows.get(runId)).state, "waiting");

    await app.events.publish("user.activated", { userId: "u_1" });
    await app.clock.tick("1m");                       // now it waits for a person
    const [pending] = app.agents.pendingApprovals();
    assert.equal(pending?.call.action, "credits.grant");
    app.agents.approve(pending!.id, { kind: "user", id: "usr_1" });
    await app.clock.tick("1m");

    const run = await app.workflows.get(runId);
    assert.equal(run.state, "completed");
    assert.deepEqual(run.output, { activated: true, granted: true });
    assert.deepEqual(run.history.map((h) => h.kind), ["step", "step", "sleep", "waitFor", "approve", "step"]);
  });

  it("workflows AC9 times out the wait and finishes without the grant", async () => {
    const app = createTestApp();
    const { runId } = await app.workflows.start(onboarding, { userId: "u_2" });
    await app.clock.tick("11d");
    const run = await app.workflows.get(runId);
    assert.equal(run.state, "completed");
    assert.deepEqual(run.output, { activated: false });
  });
});

npx mainsdk check --env prod
node --test app/workflows/onboarding.test.ts

Goal: turn <multi-step process> into one durable workflow.
Touch: main.yaml (workflows), main.env.dev.yaml (workflows.driver: local), one workflow file, the code that calls workflows.start(), one test.
Do: put every side effect, clock read, random value and network call inside a step; keep step results to JSON ids and small values; start runs with an idempotencyKey; give changed steps a new version.
Do not: edit the steps of a version that has live runs, use Date.now() or fetch outside a step, set the local driver in main.yaml, or loosen a check.
Verify: npx mainsdk check --env prod, then node --test on the workflow's test file.
Stop and ask if: a step has no safe way to run twice, or an approval needs a person who is not named.