@sanoma-ai/workflows 0.11.14 → 0.11.16

package/drizzle/company/meta/_journal.json

@@ -15,6 +15,13 @@
       "when": 1793827495694,
       "tag": "0001_wakeup_row",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1793857547422,
+      "tag": "0002_runs_tell_the_app",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanoma-ai/workflows",
-  "version": "0.11.14",
+  "version": "0.11.16",
   "description": "Business processes as TypeScript functions, run durably on DBOS",
   "keywords": [
     "approvals",

package/src/app-steps.ts

@@ -0,0 +1,67 @@
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import type { AppAction, AppRunner, AppStepContext, AppSteps } from "./app-workflows.ts";
+import type { ResolvedConfig, SanomaConfig } from "./config.ts";
+import { type Run, runNow } from "./run.ts";
+import { APPLY_WORKFLOW } from "./shared.ts";
+
+// The app's built-ins' steps (`app-workflows.ts` is held to the workflow lint and imports no
+// DBOS): each app step in a DBOS step of its own, given what the worker has (`WorkerState.appSteps`),
+// and the apply after it started as a child run. Each reads its run from `currentRun`.
+
+/** What a worker started with the app's steps keeps for them (`WorkerState.appSteps`). */
+export interface WorkerApp {
+  steps: AppSteps;
+  config: SanomaConfig;
+  resolved: ResolvedConfig;
+}
+
+/** What a worker started without the app's steps answers a run of one of the app's built-ins. */
+export const NO_APP_STEPS =
+  "This worker runs none of the app's actions: start it with the app's steps (`WorkerOptions.app`), as `sanoma serve` and `sanoma worker` do";
+
+/** The app's steps the run's worker was given; thrown, saying `missing`, when it was given none. */
+export function appStepsOf(run: Run, missing: string): WorkerApp {
+  const app = run.state.appSteps;
+  if (!app) throw new Error(missing);
+  return app;
+}
+
+/** What the run's app step is given (`AppStepContext`): the worker's own client, connected on first use, and what the worker has. */
+export async function stepContext(run: Run, { config, resolved }: WorkerApp): Promise<AppStepContext> {
+  const { state } = run;
+  return {
+    client: await state.client(),
+    ...(state.source && { source: state.source }),
+    serially: state.serially,
+    config,
+    resolved,
+    by: run.actor,
+    runId: run.id,
+  };
+}
+
+/** The app's step `name` with `input`, in a DBOS step of the run's (`app:<name>`). */
+function step(run: Run, name: AppAction, input: unknown): Promise<any> {
+  const app = appStepsOf(run, NO_APP_STEPS);
+  return DBOS.runStep(
+    async () =>
+      (app.steps[name] as (step: AppStepContext, input: unknown) => Promise<unknown>)(
+        await stepContext(run, app),
+        input,
+      ),
+    { name: `app:${name}` },
+  );
+}
+
+/** The runner the app's built-ins run their work through. */
+export const appRunner: AppRunner = {
+  step: (name, input) => step(runNow("An app step"), name, input) as ReturnType<AppSteps[typeof name]>,
+  async stepThenApply(name, input) {
+    const run = runNow("An app step");
+    const { apply, ...rest } = await step(run, name, input);
+    // Its child, as its own actor, not waited for: an apply may wait for its plan's approval.
+    const runId = `${run.id}:apply`;
+    await run.state.startRun(APPLY_WORKFLOW, runId, { input: apply, startedBy: run.actor });
+    return { ...rest, runId };
+  },
+};

package/src/app-workflows.ts

@@ -0,0 +1,251 @@
+import { z } from "zod";
+import type { ApplyInput } from "./apply.ts";
+import type { ChatTurnInput, ChatTurnOutput } from "./chat-workflow.ts";
+import type { ResolvedConfig, SanomaConfig } from "./config.ts";
+import type { SanomaClient } from "./client.ts";
+import { defineWorkflow, type Principal, type WorkflowDefinition } from "./define.ts";
+import { AtSchema } from "./description.ts";
+import type {
+  ADOPT_WORKFLOW,
+  CONNECT_EXISTING_WORKFLOW,
+  GO_LIVE_HOST_WORKFLOW,
+  GO_LIVE_WORKFLOW,
+  PATCH_WORKFLOW,
+  WorkflowFn,
+} from "./shared.ts";
+import type { Source } from "./source.ts";
+
+// The app's own actions on the company's repository, as built-in workflows: the app starts each
+// (its pages through `api.<name>`, polling `.result`) and the worker runs it, since only the
+// worker has the checkout. What each does is the app's, given to the worker as `AppSteps`
+// (`WorkerOptions.app`, `@sanoma-ai/app/steps`), and each is called in a step of its own run
+// (`app-steps.ts`), its writes to the checkout one at a time per worker. Workflows like any other, held to
+// the same lint: no DBOS here, and no operation, so nothing goes through `ctx`.
+
+/** Adopt's input: a drift run, a resource it found drifted, and the fields whose value at the vendor to write into the resource's data file. */
+export const AdoptInput = z.object({
+  runId: z.string().min(1),
+  id: z.string().min(1),
+  paths: z.array(z.string().min(1)).min(1),
+});
+export type AdoptInput = z.infer<typeof AdoptInput>;
+
+/**
+ * A form's Save: a declaration the description names (a resource, a collection, a site or an
+ * app, by its `at`), and the fields to set in it, by dotted path as `setFields` takes them, each
+ * to a JSON value.
+ */
+export const PatchInput = z.object({
+  at: AtSchema,
+  fields: z.record(z.string().min(1), z.json()).refine((fields) => Object.keys(fields).length > 0, "Set a field"),
+});
+export type PatchInput = z.infer<typeof PatchInput>;
+
+/**
+ * What going live chooses: who holds the repository, the database's region (and size, when it
+ * takes one), Supabase's organization for a Supabase project, the host's port.
+ */
+export const GoLiveInput = z.object({
+  owner: z.string().regex(/^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/, "Choose a GitHub account or organization"),
+  /** The repository's name, and the database's and the host's. */
+  name: z
+    .string()
+    .regex(/^[a-z0-9][a-z0-9-]{0,62}$/, "Lower case letters, digits and hyphens, starting with a letter or digit"),
+  organization: z.string().min(1, "Choose a Supabase organization").optional(),
+  region: z.string().min(1, "Choose a region"),
+  size: z.string().min(1).optional(),
+  /** The database type the page showed (`GoLiveChoices.database`): refused when going live would now choose another. */
+  database: z.string().min(1).optional(),
+  /** The host type the page showed (`GoLiveChoices.host`): refused when going live would now choose another. */
+  host: z.string().min(1).optional(),
+  port: z.number().int().min(1024, "A port from 1024").max(65535, "A port up to 65535"),
+});
+export type GoLiveInput = z.infer<typeof GoLiveInput>;
+
+/** Going live's second half takes nothing: what it pushes and applies is in `infra.ts`. */
+export const GoLiveHostInput = z.strictObject({});
+export type GoLiveHostInput = z.infer<typeof GoLiveHostInput>;
+
+/** An existing GitHub repository (`owner/name`: the owner is always written) and a Supabase project's ref, either or both. */
+export const ConnectExistingInput = z
+  .object({
+    repository: z
+      .string()
+      .trim()
+      .regex(/^[\w-]+\/(?!\.\.?$)[\w.-]+$/, "Enter a repository as owner/name")
+      .optional(),
+    project: z
+      .string()
+      .trim()
+      .regex(/^[a-z0-9]+$/, "Enter a project's ref: lowercase letters and digits")
+      .optional(),
+  })
+  .refine((r) => r.repository || r.project, { message: "Enter a repository, a project's ref, or both" });
+export type ConnectExistingInput = z.infer<typeof ConnectExistingInput>;
+
+/** A data file written, relative to the root, and its commit, when the worker has a repository. */
+export interface Written {
+  file: string;
+  revision?: string;
+}
+
+/** What a Save lands as: the change opened for review (its run id), when the repository has a remote; otherwise the file written. */
+export type PatchOutput = { change: string } | Written;
+
+/** What going live's runs answer: the apply run each started (`<run>:apply`), which the page follows. */
+export interface GoLiveOutput {
+  runId: string;
+}
+
+/**
+ * What connecting answers: the data file it wrote and its text; its commit, on `branch` (with its
+ * `diff`) when the repository has a remote and the change waits for a person to merge it; and the
+ * apply run that binds what it declares.
+ */
+export interface ConnectExistingOutput extends Written {
+  text: string;
+  branch?: string;
+  diff?: string;
+  runId: string;
+}
+
+/**
+ * What an app step is given: the worker's own client (connected on first use, closed when the
+ * worker stops), its repository (`WorkerOptions.source`) and the lock its writes there take, the
+ * config and its resolution, who started the run (`by`, as `SanomaClient.start` admitted them)
+ * and the run's id.
+ */
+export interface AppStepContext {
+  client: SanomaClient;
+  source?: Source;
+  /**
+   * Runs `write` once the worker's write before it has settled (`WorkerState.serially`): what a step
+   * holds around reading and writing the checkout and committing, so two never write one file.
+   */
+  serially<T>(write: () => Promise<T>): Promise<T>;
+  config: SanomaConfig;
+  resolved: ResolvedConfig;
+  by: Principal;
+  runId: string;
+}
+
+/**
+ * What a chat turn's step is given besides an app step's: when to stop (a new message came, or the
+ * worker stopped), a way to take the sign-in codes the person pastes for this turn, and whether
+ * the turn had begun before, on a worker that restarted under it.
+ */
+export interface ChatTurnContext extends AppStepContext {
+  signal: AbortSignal;
+  /** Hands each code pasted for this turn (`SanomaClient.turnCode`) to `listener`, until the function it returns is called. */
+  onCode(listener: (code: string) => void): () => void;
+  /** The turn had begun (`Chats.begin`) before the worker restarted: it settles what it left, and runs nothing again. */
+  resumed: boolean;
+}
+
+/**
+ * The app's own actions, which a worker runs (`WorkerOptions.app`): one method per built-in
+ * workflow of the app's, each called in a DBOS step of its run, its writes to the checkout under
+ * `AppStepContext.serially`. A step refuses by throwing: a `SanomaError` with the code the page
+ * branches on (`invalid_input` with its `issues`, or a `field`; `not_approver`), else an error
+ * whose message the page shows. What a step returns is checkpointed, so it is JSON. One that
+ * applies after its write returns what apply plans (`apply`), which its run starts as a child.
+ */
+export interface AppSteps {
+  /** Adopt: what the vendor holds for drifted fields, by the drift run's report, into their data file, committed. */
+  adopt(step: AppStepContext, input: AdoptInput): Promise<Written>;
+  /** A form's Save: the fields set in the declaration's file, as a change for review with a remote, else written and committed. */
+  patch(step: AppStepContext, input: PatchInput): Promise<PatchOutput>;
+  /** Going live's first half: `infra.ts` written for the choices and committed; what apply makes first. */
+  goLive(step: AppStepContext, input: GoLiveInput): Promise<{ apply: ApplyInput }>;
+  /** Going live's second half: `main` pushed to the repository apply made; the host (and its wakeup) to apply. */
+  goLiveHost(step: AppStepContext, input: GoLiveHostInput): Promise<{ apply: ApplyInput }>;
+  /** An existing repository and/or project declared in `infra.ts` and committed; the apply that only binds them. */
+  connectExisting(
+    step: AppStepContext,
+    input: ConnectExistingInput,
+  ): Promise<Omit<ConnectExistingOutput, "runId"> & { apply: ApplyInput }>;
+  /**
+   * A chat turn: the reply to the person's message, by the chat's engine, written to the chat's
+   * transcript and, as it streams, to its chunks (`Chats.append`, then `Chats.end`). It writes its
+   * own draft, not the checkout.
+   */
+  chat(step: ChatTurnContext, input: ChatTurnInput): Promise<ChatTurnOutput>;
+}
+
+/** The app's steps an action's run calls (`AppRunner`): all but the chat's turn, which its own workflow runs. */
+export type AppAction = Exclude<keyof AppSteps, "chat">;
+
+/** The actions whose step answers what to apply after its write. */
+type Applying = {
+  [K in AppAction]: Awaited<ReturnType<AppSteps[K]>> extends { apply: ApplyInput } ? K : never;
+}[AppAction];
+
+/** What a built-in of the app's runs its work through (`appRunner`, in `app-steps.ts`). */
+export interface AppRunner {
+  /** The app's step `name` with `input`, in a DBOS step of this run; refused when the worker runs no app steps. */
+  step<K extends AppAction>(name: K, input: Parameters<AppSteps[K]>[1]): ReturnType<AppSteps[K]>;
+  /**
+   * The step, then the apply it answers started as a child run of this one (`<run>:apply`), as its
+   * own actor, without waiting for it: what the step answered besides, with that run's id.
+   */
+  stepThenApply<K extends Applying>(
+    name: K,
+    input: Parameters<AppSteps[K]>[1],
+  ): Promise<Omit<Awaited<ReturnType<AppSteps[K]>>, "apply"> & { runId: string }>;
+}
+
+/** The app's built-ins as its pages call them, by api name (`apiNameOf`): started, then their `.result` polled. */
+export interface AppApi {
+  adopt: WorkflowFn<AdoptInput, Written>;
+  patch: WorkflowFn<PatchInput, PatchOutput>;
+  goLive: WorkflowFn<GoLiveInput, GoLiveOutput>;
+  goLiveHost: WorkflowFn<GoLiveHostInput, GoLiveOutput>;
+  connectExisting: WorkflowFn<ConnectExistingInput, ConnectExistingOutput>;
+}
+
+/** The built-in workflows of the app's actions, over `runner`: `resolveConfig` adds them to every config. */
+export function appWorkflows(runner: AppRunner): WorkflowDefinition<any, any>[] {
+  return [
+    defineWorkflow({
+      // The literal, held to the one name: the outline finds a workflow by a string, or a const of its own file.
+      name: "adopt" satisfies typeof ADOPT_WORKFLOW,
+      title: "Adopt a vendor's value",
+      trigger: "manual",
+      input: AdoptInput,
+      uses: [],
+      run: async (_ctx, input) => runner.step("adopt", input),
+    }),
+    defineWorkflow({
+      name: "patch" satisfies typeof PATCH_WORKFLOW,
+      title: "Save a declaration",
+      trigger: "manual",
+      input: PatchInput,
+      uses: [],
+      run: async (_ctx, input) => runner.step("patch", input),
+    }),
+    defineWorkflow({
+      name: "go-live" satisfies typeof GO_LIVE_WORKFLOW,
+      title: "Go live",
+      trigger: "manual",
+      input: GoLiveInput,
+      uses: [],
+      run: async (_ctx, input): Promise<GoLiveOutput> => runner.stepThenApply("goLive", input),
+    }),
+    defineWorkflow({
+      name: "go-live-host" satisfies typeof GO_LIVE_HOST_WORKFLOW,
+      title: "Push and run the host",
+      trigger: "manual",
+      input: GoLiveHostInput,
+      uses: [],
+      run: async (_ctx, input): Promise<GoLiveOutput> => runner.stepThenApply("goLiveHost", input),
+    }),
+    defineWorkflow({
+      name: "connect-existing" satisfies typeof CONNECT_EXISTING_WORKFLOW,
+      title: "Connect an existing repository or database",
+      trigger: "manual",
+      input: ConnectExistingInput,
+      uses: [],
+      run: async (_ctx, input): Promise<ConnectExistingOutput> => runner.stepThenApply("connectExisting", input),
+    }),
+  ];
+}

package/src/apply-steps.ts

@@ -4,7 +4,7 @@ import type { ApplyDeclared, ApplySteps, PlannedCall } from "./apply.ts";
 import { decide } from "./call.ts";
 import type { Approver } from "./define.ts";
 import { type Binding, type Bindings, diffLockfiles, LOCKFILE, readLockfile, writeLockfile } from "./lockfile.ts";
-import { currentRun, type Run } from "./run.ts";
+import { runNow } from "./run.ts";
 import { APPLY_WORKFLOW } from "./shared.ts";
 
 // The apply workflow's steps that call no vendor: reading the data files, asking the policy
@@ -17,12 +17,6 @@ const WRITE_STEP = "apply:lockfile";
 /** How many of the latest apply runs are searched for the lockfile one last wrote. */
 const RUNS_SEARCHED = 100;
 
-const runNow = (): Run => {
-  const run = currentRun.getStore();
-  if (!run) throw new Error("An apply step ran outside its run");
-  return run;
-};
-
 /**
  * The bindings the latest apply run that wrote the lockfile wrote last, from its steps; undefined
  * when none of the latest `RUNS_SEARCHED` did. A sandbox run writes none.
@@ -68,7 +62,7 @@ export function applySteps(
     holds: (calls: PlannedCall[]) =>
       DBOS.runStep(
         async (): Promise<Approver | undefined> => {
-          const run = runNow();
+          const run = runNow("An apply step");
           for (const { op: id, input, connection } of calls) {
             const op = run.state.ops.get(id)!;
             // Parsed as the call will be, so the policy sees the same input with its defaults.
@@ -87,7 +81,7 @@ export function applySteps(
     // step whose output is what it wrote. A sandbox run keeps its lockfile in memory: the run's
     // report has it.
     write: async (key: string, binding: Binding | undefined, message: string, moved?: string) => {
-      const run = runNow();
+      const run = runNow("An apply step");
       if (run.sandbox !== undefined || root === undefined) return { written: false };
       const { source } = run.state;
       const { revision } = await DBOS.runStep(

package/src/approvals.ts

@@ -5,7 +5,7 @@ import { RejectedError, WithdrawnError } from "./errors.ts";
 import { entry, write } from "./ledger.ts";
 import { warn } from "./log.ts";
 import type { Placed } from "./call.ts";
-import type { Run } from "./run.ts";
+import { recordSandboxChecks, type Run } from "./run.ts";
 import { readPeople } from "./resources.ts";
 import { approverLabel, isVisitor, OWN_CHANGE, refusalOf } from "./shared.ts";
 
@@ -140,6 +140,8 @@ export async function awaitApproval(
       { key: state.id, at: state.requestedAt },
     ),
   );
+  // A sandbox run's checks as it starts to wait, for the app: awaited, since Cucumber runs one at a time in a process.
+  await recordSandboxChecks(run);
   for (;;) {
     // A decision comes from a request (`SanomaClient.decide`), which wakes a stopped worker: no deadline.
     const raw = await run.state.deadlines.waiting(run.id, { kind: "approval" }, () =>

package/src/call.ts

@@ -59,7 +59,8 @@ const takenByDbos = (err: unknown) =>
  * cancelled the run or another process took it over, or the run's worker is stopping and the
  * error has none of our codes. `stop()` marks the worker stopped before DBOS shuts down, so from
  * then on whatever fails without a code (DBOS's "system database has been shut down", pg's
- * closed pool) is the shutdown, and the run recovered on the next worker records how it ends.
+ * closed pool) is the shutdown. `runWorkflow` then keeps DBOS from recording it, so the run
+ * recovered on the next worker records how it ends.
  * A coded failure then (a driver's final answer, a denial, a rejection) is still the outcome:
  * DBOS records the run's error and never runs it again, so the ledger records it too. Narrower
  * than `isRunControlError`: DBOS's other errors (a run that is not deterministic) end the run

package/src/change-steps.ts

@@ -12,7 +12,6 @@ import {
   type ChangeFacts,
   type ChangeState,
   type ChangeVerified,
-  followBase,
   repositoryOf,
   isRules,
   mayDeclarePeople,
@@ -25,7 +24,7 @@ import { isRunControlError } from "./errors.ts";
 import { warn } from "./log.ts";
 import { inside } from "./paths.ts";
 import { peopleSources } from "./resources.ts";
-import { currentRun, type Run } from "./run.ts";
+import { runNow, type Run } from "./run.ts";
 import {
   AGENTS,
   APPLY_WORKFLOW,
@@ -43,12 +42,6 @@ import type { CheckResult, RemoteHalf } from "./source.ts";
 // change-workflow.ts, which is held to the workflow lint and imports no DBOS; each reads its run
 // from `currentRun`.
 
-const runNow = (): Run => {
-  const run = currentRun.getStore();
-  if (!run) throw new Error("A change step ran outside its run");
-  return run;
-};
-
 /** True when the file at `path` is a people file (`mayDeclarePeople`), one `readPeople` would load; false when there is none. */
 const fileDeclaresPeople = async (path: string) => mayDeclarePeople(await readFile(path, "utf8").catch(() => ""));
 
@@ -135,7 +128,7 @@ export function changeSteps({ remotes, hosts }: ChangeStepsOptions): ChangeSteps
   const settled = (number: number) =>
     DBOS.runStep(
       async (): Promise<ChangeEvent> => {
-        const { host } = await repositoryOf(remotes, runNow().state.secrets);
+        const { host } = await repositoryOf(remotes, runNow("A change step").state.secrets);
         const pr = await host.pullRequest(number);
         if (pr.state === "merged") return { kind: "merged", sha: pr.mergeSha ?? pr.head };
         return pr.state === "closed" ? { kind: "closed" } : { kind: "commits" };
@@ -157,7 +150,7 @@ export function changeSteps({ remotes, hosts }: ChangeStepsOptions): ChangeSteps
     plan: (id, check) =>
       DBOS.runStep(
         async (): Promise<ChangeFacts> => {
-          const run = runNow();
+          const run = runNow("A change step");
           const source = sourceOfRun();
           if (!source.diff || !source.draft) throw new Error("This repository keeps no drafts (`Source.diff`)");
           const [{ files }, draft] = await Promise.all([source.diff(id), source.draft(id)]);
@@ -205,7 +198,7 @@ export function changeSteps({ remotes, hosts }: ChangeStepsOptions): ChangeSteps
     ahead: (merge) =>
       DBOS.runStep(
         async (): Promise<ChangeDecision> => {
-          const run = runNow();
+          const run = runNow("A change step");
           const op = run.state.ops.get(CHANGE_MERGE)!;
           const decision = await decide(run, op, op.input.parse(merge));
           if (decision.kind === "deny") return { answer: "deny", reason: decision.reason };
@@ -226,7 +219,7 @@ export function changeSteps({ remotes, hosts }: ChangeStepsOptions): ChangeSteps
       ),
 
     async next(number) {
-      const run = runNow();
+      const run = runNow("A change step");
       for (;;) {
         // An event comes from a request (`SanomaClient.changeEvent`), which wakes a stopped worker: no deadline.
         const event = await received(run, RECV_SECONDS);
@@ -234,15 +227,15 @@ export function changeSteps({ remotes, hosts }: ChangeStepsOptions): ChangeSteps
       }
     },
 
-    queued: (number) => drain(runNow(), () => settled(number)),
+    queued: (number) => drain(runNow("A change step"), () => settled(number)),
 
-    retire: (reason) => withdrawApprovals(runNow(), CHANGE_MERGE, reason),
+    retire: (reason) => withdrawApprovals(runNow("A change step"), CHANGE_MERGE, reason),
 
     async deploy() {
-      const run = runNow();
+      const run = runNow("A change step");
       // The checkout moves to the merge first, so the hosts and what apply reads are the merged ones.
       // Merged already: a deploy that fails is the change's to report, not a failed run.
-      const follow: ChangeDeploy["follow"] = await DBOS.runStep(() => followBase(remotes, run.state.secrets), {
+      const follow: ChangeDeploy["follow"] = await DBOS.runStep(() => run.state.followMain(), {
         name: "change:follow",
       });
       const declared = run.state.workflows.has(APPLY_WORKFLOW)
@@ -254,7 +247,7 @@ export function changeSteps({ remotes, hosts }: ChangeStepsOptions): ChangeSteps
     },
 
     async verify({ apply }) {
-      const run = runNow();
+      const run = runNow("A change step");
       if (apply === undefined || !run.state.workflows.has(DRIFT_WORKFLOW)) return undefined;
       const { runId, output, error } = await child(run, DRIFT_WORKFLOW, "verify", {});
       const applied = new Set(apply.hosts);

package/src/chat-steps.ts

@@ -0,0 +1,117 @@
+import { DBOS, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
+import { appStepsOf, stepContext } from "./app-steps.ts";
+import type { ChatSteps, ChatTurnOutput } from "./chat-workflow.ts";
+import { ChatTell } from "./chat-workflow.ts";
+import { isRunControlError } from "./errors.ts";
+import { warn } from "./log.ts";
+import { runNow } from "./run.ts";
+import { openChatCode } from "./seal.ts";
+import { CHAT_TOPIC, errorMessage } from "./shared.ts";
+
+// The chat workflow's steps (`chat-workflow.ts` is held to the workflow lint and imports no DBOS):
+// the wait for the turn before, the turn itself in a step of its own (the app's `AppSteps.chat`,
+// given what an app step is), and what the run is told meanwhile, handed to the turn under way
+// through the turns these steps keep. The turn's step and the run's `recv`s run side by side:
+// DBOS numbers each call as it is made, so a replay meets them in the same order.
+
+/** What a worker without the app's steps answers a chat turn: its run fails at once, saying where the agent runs. */
+export const NO_CHAT_STEPS =
+  "No agent runs on this instance's worker: chat from the Mac app, or where `sanoma dev` or `sanoma serve` runs the company's checkout";
+
+/**
+ * How long one `recv` waits before it asks again: the turn's own end ends the loop once its step
+ * has settled, should its `ended` not have reached the run. A turn waits for its person's sign-in
+ * as long as it lets them.
+ */
+const RECV_SECONDS = 10 * 60;
+
+/** A chat turn under way: how to stop it, and who takes a code pasted for its sign-in. */
+interface LiveTurn {
+  stop: AbortController;
+  code?: (code: string) => void;
+}
+
+/** The chat workflow's steps. */
+export function chatSteps(): ChatSteps {
+  /** Each turn under way in this process, by its run's id: what `tell` hands a message to the run to. */
+  const turns = new Map<string, LiveTurn>();
+  return {
+    async after(runId) {
+      const run = runNow("A chat step");
+      try {
+        await run.state.deadlines.waiting(run.id, { kind: "run" }, () => DBOS.retrieveWorkflow(runId).getResult());
+      } catch (err) {
+        // However the turn before ended, it has: a failed or cancelled one too.
+        if (isRunControlError(err) && !(err instanceof DBOSErrors.DBOSAwaitedWorkflowCancelledError)) throw err;
+      }
+    },
+
+    turn(input) {
+      const run = runNow("A chat step");
+      // Thrown, not a rejection: the run fails at once, before it waits for an end no turn would tell.
+      const app = appStepsOf(run, NO_CHAT_STEPS);
+      const live: LiveTurn = { stop: new AbortController() };
+      // Kept for `tell` before the step starts, so a stop it reads at once finds the turn.
+      turns.set(run.id, live);
+      const done = DBOS.runStep(
+        async (): Promise<ChatTurnOutput> => {
+          try {
+            const step = await stepContext(run, app);
+            const resumed = !(await step.client.chats.begin(input.chat, run.id));
+            return await app.steps.chat(
+              {
+                ...step,
+                // Stopped by a new message, or once the worker has stopped, so no agent goes on without it.
+                signal: AbortSignal.any([live.stop.signal, run.state.shutdown]),
+                onCode(listener) {
+                  live.code = listener;
+                  return () => {
+                    if (live.code === listener) live.code = undefined;
+                  };
+                },
+                resumed,
+              },
+              input,
+            );
+          } finally {
+            // From the step: DBOS keeps no record of it, and a step done again tells it again. A
+            // send that fails leaves the step's own answer or error standing: `tell` sees it settled.
+            await DBOS.send(run.id, { kind: "ended" } satisfies ChatTell, CHAT_TOPIC).catch((err: unknown) =>
+              warn(`run ${run.id}: could not tell the run its turn ended: ${errorMessage(err)}`),
+            );
+          }
+        },
+        { name: "chat:turn" },
+      );
+      const forget = () => {
+        if (turns.get(run.id) === live) turns.delete(run.id);
+      };
+      // The run awaits it once `tell` says it ended: handled meanwhile, so its failure is not unhandled.
+      done.then(forget, forget);
+      return done;
+    },
+
+    async tell() {
+      const run = runNow("A chat step");
+      // Its turn's step has settled (it is no longer under way here): nothing more to hand it.
+      if (!turns.has(run.id)) return false;
+      // No deadline: the turn's step is executing all the while, so the run is busy, not waiting.
+      const raw = await DBOS.recv<unknown>(CHAT_TOPIC, { timeoutSeconds: RECV_SECONDS });
+      if (raw === null || raw === undefined) return turns.has(run.id);
+      const told = ChatTell.safeParse(raw);
+      if (!told.success) {
+        warn(`run ${run.id}: a message on ${CHAT_TOPIC} is none a chat turn takes, so it is ignored`);
+        return true;
+      }
+      const live = turns.get(run.id);
+      if (told.data.kind === "ended") return false;
+      if (told.data.kind === "stop") live?.stop.abort();
+      else {
+        const code = openChatCode(told.data.sealed, run.id);
+        if (code === undefined) warn(`run ${run.id}: a sign-in code not sealed for it is ignored`);
+        else live?.code?.(code);
+      }
+      return true;
+    },
+  };
+}