@sanoma-ai/workflows 0.11.14 → 0.11.16

package/src/db/company.ts

@@ -1,4 +1,4 @@
-import type { UIMessage } from "ai";
+import type { UIMessage, UIMessageChunk } from "ai";
 import { sql } from "drizzle-orm";
 import {
   bigserial,
@@ -14,6 +14,7 @@ import {
 } from "drizzle-orm/pg-core";
 import type { ConnectionHealth, ConnectionStatus } from "../connection.ts";
 import type { LedgerRecord } from "../ledger.ts";
+import type { RunCheck } from "../scenario.ts";
 import type { SecretLocation } from "../secret-store.ts";
 
 // The runtime's tables in a company's database, beside DBOS's: what `prepareDatabase` makes and
@@ -86,7 +87,7 @@ export const wakeup = pgTable(
   (t) => [check("sanoma_wakeup_one_row", sql`${t.id} = 1`)],
 );
 
-/** The operator agent's chats (`chats.ts`): who each is for, its engine and its draft. */
+/** The operator agent's chats (`chats.ts`): who each is for, its engine, its draft and the turn last begun (its run's id). */
 export const chats = pgTable(
   "sanoma_chats",
   {
@@ -96,6 +97,7 @@ export const chats = pgTable(
     draftId: text(),
     title: text().notNull(),
     createdAt: when().notNull().defaultNow(),
+    turn: text(),
   },
   (t) => [index("sanoma_chats_person").on(t.person, t.createdAt)],
 );
@@ -114,6 +116,24 @@ export const chatMessages = pgTable(
   (t) => [primaryKey({ columns: [t.chatId, t.id] })],
 );
 
+/**
+ * The reply a chat turn streams, as the worker writes it (`Chats.append`): its UI message stream's
+ * chunks in `seq` order, then a row with none, its end. The app streams them to the browser; a
+ * chat's turn's rows go when its next turn begins.
+ */
+export const chatChunks = pgTable(
+  "sanoma_chat_chunks",
+  {
+    chatId: text()
+      .notNull()
+      .references(() => chats.id, { onDelete: "cascade" }),
+    runId: text().notNull(),
+    seq: integer().notNull(),
+    chunk: jsonb().$type<UIMessageChunk>(),
+  },
+  (t) => [primaryKey({ columns: [t.runId, t.seq] }), index("sanoma_chat_chunks_chat").on(t.chatId)],
+);
+
 /** The api tokens (`tokens.ts`): each one's SHA-256, never the token, whom it acts for, its groups, and when it was revoked. */
 export const apiTokens = pgTable("sanoma_api_tokens", {
   id: text().primaryKey(),
@@ -171,3 +191,30 @@ export const connectionSetups = pgTable(
   },
   (t) => [primaryKey({ columns: [t.connectionId, t.revision] })],
 );
+
+/**
+ * How far each app taken from a source is behind it, as the worker last checked (`writeAppsBehind`):
+ * one row per app folder, its count of commits or why it could not be told.
+ */
+export const appBehind = pgTable(
+  "sanoma_app_behind",
+  {
+    folder: text().primaryKey(),
+    behind: integer(),
+    error: text(),
+    checkedAt: when().notNull().defaultNow(),
+  },
+  (t) => [check("sanoma_app_behind_one_answer", sql`(${t.behind} IS NULL) <> (${t.error} IS NULL)`)],
+);
+
+/** Each sandbox run's checks against its scenario, as the worker last ran them (`recordChecks` in sandbox.ts): one row per run. */
+export const runChecks = pgTable(
+  "sanoma_run_checks",
+  {
+    runId: text().primaryKey(),
+    checks: jsonb().$type<RunCheck[]>(),
+    error: text(),
+    checkedAt: when().notNull().defaultNow(),
+  },
+  (t) => [check("sanoma_run_checks_one_answer", sql`(${t.checks} IS NULL) <> (${t.error} IS NULL)`)],
+);

package/src/db.ts

@@ -1,17 +1,20 @@
 import { DBOS, DBOSClient } from "@dbos-inc/dbos-sdk";
 import { setTimeout as delay } from "node:timers/promises";
-import { and, eq, inArray, lte, ne, sql } from "drizzle-orm";
+import { and, eq, inArray, lte, ne, notInArray, sql } from "drizzle-orm";
 import { DrizzleQueryError } from "drizzle-orm/errors";
 import { drizzle, type NodePgClient, type NodePgQueryResultHKT } from "drizzle-orm/node-postgres";
 import { type PgDatabase, PgPreparedQuery } from "drizzle-orm/pg-core";
 import { Client, Pool } from "pg";
-import { inviteRequests } from "./db/company.ts";
+import { appBehind, inviteRequests, runChecks } from "./db/company.ts";
 import { workflowStatus } from "./db/dbos.ts";
 import { applyMigrations, COMPANY_MIGRATIONS, migrationsApplied } from "./db/migrate.ts";
 import { warn } from "./log.ts";
+import type { RunChecks } from "./scenario.ts";
 import { errorMessage } from "./shared.ts";
 
-// The runtime's own tables live in the config's database, beside DBOS's (`db/company.ts`). What
+// The runtime's own tables live in the config's database, beside DBOS's (`db/company.ts`), among
+// them what the worker tells the app (how far each app is behind its source, a sandbox run's
+// checks). What
 // the stores share is here: Drizzle over a `pg` pool or connection (`databaseOn`), the one
 // preparation of a database, which applies the generated migrations under a lock, and a pool that
 // opens once it is prepared and survives a dropped connection.
@@ -377,3 +380,48 @@ export async function spendInviteRequest(db: Db, nonce: string, expiresAt: Date)
     .returning({ nonce: inviteRequests.nonce });
   return spent.length === 1;
 }
+
+/** How far an app is behind its source (`Source.behind`), or why that could not be told. */
+export type AppBehind = { behind: number } | { error: string };
+
+/** Sets each app's row to what was told of it now, and drops the rows of apps no longer listed. */
+export async function writeAppsBehind(db: Db, told: ReadonlyMap<string, AppBehind>): Promise<void> {
+  const folders = [...told.keys()];
+  await db.delete(appBehind).where(folders.length ? notInArray(appBehind.folder, folders) : undefined);
+  for (const [folder, answer] of told) {
+    const row = "behind" in answer ? { behind: answer.behind, error: null } : { behind: null, error: answer.error };
+    await db
+      .insert(appBehind)
+      .values({ folder, ...row })
+      .onConflictDoUpdate({ target: appBehind.folder, set: { ...row, checkedAt: sql`now()` } });
+  }
+}
+
+/** The app `folder`'s row: how far it is behind its source, or why not; undefined when the worker has not told it. */
+export async function readAppBehind(db: Db, folder: string): Promise<AppBehind | undefined> {
+  const [row] = await db
+    .select({ behind: appBehind.behind, error: appBehind.error })
+    .from(appBehind)
+    .where(eq(appBehind.folder, folder));
+  if (!row) return undefined;
+  return row.error === null ? { behind: row.behind! } : { error: row.error };
+}
+
+/** Sets the run's checks (`RunChecks`), replacing what was there. */
+export async function writeRunChecks(db: Db, runId: string, checks: RunChecks): Promise<void> {
+  const row = "checks" in checks ? { checks: checks.checks, error: null } : { checks: null, error: checks.error };
+  await db
+    .insert(runChecks)
+    .values({ runId, ...row })
+    .onConflictDoUpdate({ target: runChecks.runId, set: { ...row, checkedAt: sql`now()` } });
+}
+
+/** The run's checks as the worker last ran them; undefined when it has run none. */
+export async function readRunChecks(db: Db, runId: string): Promise<RunChecks | undefined> {
+  const [row] = await db
+    .select({ checks: runChecks.checks, error: runChecks.error })
+    .from(runChecks)
+    .where(eq(runChecks.runId, runId));
+  if (!row) return undefined;
+  return row.error === null ? { checks: row.checks! } : { error: row.error };
+}

package/src/fill.ts

@@ -10,9 +10,17 @@ setFaker(faker);
 /** Seeds the generator from a name, so one name always makes up the same values. */
 export const seedFrom = (name: string) => seed(createHash("sha256").update(name).digest().readUInt32BE(0));
 
-/** The schema's value with every field `given` does not set made up, parsed by the schema. */
+/**
+ * The schema's value with every required field `given` does not set made up, parsed by the schema.
+ * Optional fields are left out, as a caller may leave them: made up, they could break a rule
+ * between fields (one of two ids, not both).
+ */
 export function fill(schema: z.ZodType, given: Record<string, unknown>): unknown {
-  return schema.parse({ ...(fake(schema) as object), ...given });
+  const made = fake(schema) as Record<string, unknown>;
+  for (const [name, field] of Object.entries(shapeOf(schema))) {
+    if (field.safeParse(undefined).success) delete made[name];
+  }
+  return schema.parse({ ...made, ...given });
 }
 
 /** An object schema's fields by name; none for any other schema. */

package/src/follow-steps.ts

@@ -0,0 +1,129 @@
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { BASE, type ChangeEvent, repositoryOf } from "./change.ts";
+import { errorCode, vendorCodeOf } from "./errors.ts";
+import type { FollowOutput, FollowSteps, FollowTarget } from "./follow-workflow.ts";
+import { warn } from "./log.ts";
+import { runNow, type Run } from "./run.ts";
+import { APPLY_WORKFLOW, HOST_CHECK_AGENT, isEnded } from "./shared.ts";
+import { draftOf, type RemoteHalf, type RepoRef } from "./source.ts";
+
+// The follow workflow's steps (`follow-workflow.ts` is held to the workflow lint and imports no
+// DBOS): where an event lands, `main` followed and its hosts applied, a draft's change told what
+// its host says. Each reads its run from `currentRun`; the worker's own client tells and reads
+// the changes, as `host-check`, and every write to the checkout is one of the worker's, one at a
+// time (`WorkerState.serially`).
+
+/** Whether two references name one repository: a host's names are compared without case. */
+const sameRepo = (a: RepoRef, b: RepoRef) =>
+  a.owner.toLowerCase() === b.owner.toLowerCase() && a.name.toLowerCase() === b.name.toLowerCase();
+
+/** What the follow steps need of the resolved config: the remote halves and the declared hosts. */
+export interface FollowStepsOptions {
+  remotes: ReadonlyMap<string, RemoteHalf>;
+  hosts(): Promise<string[]>;
+}
+
+export function followSteps({ remotes, hosts }: FollowStepsOptions): FollowSteps {
+  /** The worker's repository on its host (`repositoryOf`); undefined with no repository, remote or half for it. */
+  const repository = async (run: Run) => {
+    const { source } = run.state;
+    if (!source) return undefined;
+    return repositoryOf(remotes, run.state.secrets, source).catch((err: unknown) => {
+      if (["no_remote", "no_remote_half"].includes(vendorCodeOf(err) ?? "")) return undefined;
+      throw err;
+    });
+  };
+
+  return {
+    where: (event) =>
+      DBOS.runStep(
+        async (): Promise<FollowTarget> => {
+          const main = event.kind === "pushed" && event.branch === BASE;
+          const id = draftOf(event.branch);
+          if (!main && id === undefined) return { ignored: `${event.branch} is neither ${BASE} nor a draft's branch` };
+          const run = runNow("A follow step");
+          if (!run.state.source) return { ignored: "This worker has no repository" };
+          const found = await repository(run);
+          if (!found) return { ignored: "This worker's repository has no remote on a host a connector reads" };
+          if (!sameRepo(found.repo, event.repo)) {
+            return { ignored: `The event is ${event.repo.owner}/${event.repo.name}'s, not this repository's` };
+          }
+          return event.kind === "pushed" && main ? { main: event.head } : { draft: id! };
+        },
+        { name: "follow:where" },
+      ),
+
+    async main(head) {
+      const run = runNow("A follow step");
+      const deploy = `deploy:${head}`;
+      const declared = await DBOS.runStep(
+        async () => {
+          const client = await run.state.client();
+          const [deployed, deploying] = await Promise.all([client.run(deploy), client.changeDeploying()]);
+          if (deployed || deploying) return undefined;
+          // First, as a change's deploy does: the hosts, and what apply reads, are then main's.
+          const moved = await run.state.followMain();
+          if (!("revision" in moved)) {
+            // Nothing recorded as `deploy:<head>`: a later push deploys it.
+            throw new Error(
+              `${BASE} was not deployed: the checkout did not follow it: ${"skipped" in moved ? moved.skipped : moved.error}`,
+            );
+          }
+          return run.state.workflows.has(APPLY_WORKFLOW) ? await hosts() : [];
+        },
+        { name: "follow:main" },
+      );
+      if (!declared) return { ignored: `${deploy} has run, or a change is deploying ${BASE}` };
+      if (!declared.length) return { followed: "main" } satisfies FollowOutput;
+      // As the run's own actor, `host-check` (`SanomaClient.follow`).
+      await run.state.startRun(APPLY_WORKFLOW, deploy, { input: { only: declared }, startedBy: run.actor });
+      return { followed: "main", deploy };
+    },
+
+    draft: (event, id) =>
+      DBOS.runStep(
+        async (): Promise<{ told: ChangeEvent; key: string } | { ignored: string }> => {
+          const run = runNow("A follow step");
+          const change = await (await run.state.client()).change(id);
+          if (!change || isEnded(change.status)) return { ignored: `The draft ${id} has no open change` };
+          const key = `${event.kind}:${event.branch}:`;
+          if (event.kind === "closed") {
+            // A pull request of an earlier change of the draft is not this one's.
+            if (event.number !== change.state.pullRequest?.number) {
+              return { ignored: `Pull request #${event.number} is not the open change's` };
+            }
+            return {
+              told: event.merged && event.sha !== undefined ? { kind: "merged", sha: event.sha } : { kind: "closed" },
+              key: `${key}${event.number}:${event.sha ?? "closed"}`,
+            };
+          }
+          if (change.state.head === event.head) return { ignored: `The change is at ${event.head} already` };
+          const found = await repository(run);
+          if (!found?.source.follow) return { ignored: "This repository cannot follow its remote" };
+          const { source, url, host } = found;
+          const fetched = await run.state.serially(async () => {
+            const local = await Promise.resolve(source.head(event.branch)).catch(() => undefined);
+            if (local === event.head) return false;
+            const moved = await source.follow!({ url, token: await host.token(), ref: event.branch });
+            if ("skipped" in moved) warn(`${event.branch} did not take the host's commits: ${moved.skipped}`);
+            return !("skipped" in moved);
+          });
+          if (!fetched) return { ignored: `${event.branch} holds ${event.head} already, or cannot take it` };
+          return { told: { kind: "commits" }, key: `${key}${event.head}` };
+        },
+        { name: "follow:draft" },
+      ),
+
+    tell: (id, told, key) =>
+      DBOS.runStep(
+        async () => {
+          const client = await runNow("A follow step").state.client();
+          await client.changeEvent(id, told, { by: HOST_CHECK_AGENT, key }).catch((err: unknown) => {
+            // Ended, or gone, since it was read: nothing to tell.
+            if (!["run_ended", "run_not_found"].includes(errorCode(err) ?? "")) throw err;
+          });
+        },
+        { name: "follow:tell" },
+      ),
+  };
+}

package/src/follow-workflow.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import type { ChangeEvent } from "./change.ts";
+import { defineWorkflow, type WorkflowDefinition } from "./define.ts";
+import type { FOLLOW_WORKFLOW } from "./shared.ts";
+import type { RemoteEvent } from "./source.ts";
+
+// The built-in `follow` workflow: what a git host's webhook says happened to the company's
+// repository, done by the worker, which has the checkout. The app verifies the webhook and starts
+// the run (`SanomaClient.follow`, as the runtime's agent `host-check`, one run per event); what it
+// does is no operation, so each part is a step of `follow-steps.ts`. A workflow like any other,
+// held to the same lint.
+
+const RepoRefSchema = z.object({ owner: z.string().min(1), name: z.string().min(1) });
+
+/** What a host's webhook says happened (`RemoteEvent`): a branch pushed, or a pull request closed (merged or not). */
+export const RemoteEventSchema: z.ZodType<RemoteEvent> = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("pushed"), repo: RepoRefSchema, branch: z.string().min(1), head: z.string().min(1) }),
+  z.object({
+    kind: z.literal("closed"),
+    repo: RepoRefSchema,
+    branch: z.string().min(1),
+    number: z.number().int(),
+    merged: z.boolean(),
+    sha: z.string().min(1).optional(),
+  }),
+]);
+
+/**
+ * What a follow did: nothing, saying why (`ignored`); `main` followed, with the run that applies
+ * the declared hosts (`deploy:<head>`) when there are any; or the change of a draft told an event.
+ */
+export type FollowOutput =
+  | { ignored: string }
+  | { followed: "main"; deploy?: string }
+  | { change: string; told: ChangeEvent["kind"] };
+
+/** Where an event lands (`FollowSteps.where`): nothing, saying why; a push to `main`, of its head; or a draft's branch. */
+export type FollowTarget = { ignored: string } | { main: string } | { draft: string };
+
+/** What a follow does that is no operation, each a step of its own (`follow-steps.ts`). */
+export interface FollowSteps {
+  /**
+   * Where the event lands: ignored when the worker has no repository, the event is another
+   * repository's, or its branch is neither `main` (a push) nor a draft's.
+   */
+  where(event: RemoteEvent): Promise<FollowTarget>;
+  /**
+   * After a push of `head` to `main`: the checkout follows it, then apply on the declared hosts as
+   * `host-check`, as the run `deploy:<head>`, without waiting for it. Nothing while a change is
+   * merging or deploying, which does both itself; throws when the checkout cannot follow.
+   */
+  main(head: string): Promise<FollowOutput>;
+  /**
+   * The event for the draft `id`'s open change, when it is one to tell: a push's commits fetched
+   * into the draft first (none when the draft or the change is at that head already, or it cannot
+   * fast-forward: warned), a closed pull request of this change as `merged` or `closed`.
+   */
+  draft(event: RemoteEvent, id: string): Promise<{ told: ChangeEvent; key: string } | { ignored: string }>;
+  /** Tells the change of the draft `id` the event, once under `key`, as `host-check`: nothing once its run has ended. */
+  tell(id: string, told: ChangeEvent, key: string): Promise<void>;
+}
+
+/** The built-in follow workflow over `steps`: `resolveConfig` adds it to every config. */
+export function followWorkflow(steps: FollowSteps): 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: "follow" satisfies typeof FOLLOW_WORKFLOW,
+    title: "Follow the repository's host",
+    trigger: "manual",
+    input: RemoteEventSchema,
+    uses: [],
+    run: async (_ctx, event): Promise<FollowOutput> => {
+      const at = await steps.where(event);
+      let output: FollowOutput;
+      if ("ignored" in at) output = at;
+      else if ("main" in at) output = await steps.main(at.main);
+      else {
+        const found = await steps.draft(event, at.draft);
+        if ("ignored" in found) output = found;
+        else {
+          await steps.tell(at.draft, found.told, found.key);
+          output = { change: at.draft, told: found.told.kind };
+        }
+      }
+      return output;
+    },
+  });
+}

package/src/index.ts

@@ -27,6 +27,7 @@ export {
   retryableStatus,
   type SignInMethod,
   type SocialClients,
+  VENDOR,
   type VendorInfo,
   withSetup,
 } from "./op.ts";
@@ -93,6 +94,23 @@ export {
   type PlanStep,
 } from "./apply.ts";
 export { CALL_WORKFLOW, CallInput } from "./call-workflow.ts";
+export {
+  AdoptInput,
+  type AppApi,
+  type AppStepContext,
+  type AppSteps,
+  type ChatTurnContext,
+  ConnectExistingInput,
+  type ConnectExistingOutput,
+  GoLiveHostInput,
+  GoLiveInput,
+  type GoLiveOutput,
+  PatchInput,
+  type PatchOutput,
+  type Written,
+} from "./app-workflows.ts";
+export { type FollowOutput } from "./follow-workflow.ts";
+export { ChatTurnInput, type ChatTurnOutput } from "./chat-workflow.ts";
 export {
   ADMIN,
   type ChangeDecision,
@@ -263,7 +281,7 @@ export {
   type StoredSecret,
 } from "./client.ts";
 // A raw DBOS client on the runtime's database, for tests and tools that read DBOS directly.
-export { dbosClient } from "./db.ts";
+export { type AppBehind, dbosClient } from "./db.ts";
 // The runtime bundled where a company's files are not (the Cloudflare host's Worker): the root's
 // people, policies and app name as data, Cedar's web build, and a database it only checks.
 export { type RootSnapshot, useRootSnapshot } from "./bundled.ts";

package/src/run.ts

@@ -1,7 +1,10 @@
 import type { ConnectionRef, ConnectionRegistry, ConnectionSnapshot } from "./connection.ts";
 import { AsyncLocalStorage } from "node:async_hooks";
+import type { WorkerApp } from "./app-steps.ts";
+import type { SanomaClient } from "./client.ts";
 import type { Collection } from "./collection.ts";
 import type { DeclaredObjects } from "./config.ts";
+import type { Db } from "./db.ts";
 import type { DeadlineRegistry } from "./deadlines.ts";
 import type { ApprovalState, Approver, Principal, WorkflowDefinition } from "./define.ts";
 import type { Fake } from "./fake.ts";
@@ -53,6 +56,24 @@ export interface WorkerState {
   scenarios?: URL;
   /** The worker's `source`, when it was given one. */
   source?: Source;
+  /** The app's steps (`WorkerOptions.app`): what the app's built-ins run; none without them. */
+  appSteps?: WorkerApp;
+  /**
+   * The worker's own client, connected on first use, for its version (what it starts runs on);
+   * closed when the worker stops. What the built-ins' steps tell and read through, never a run's body.
+   */
+  client(): Promise<SanomaClient>;
+  /** Runs `write` once the one before it has settled: the worker's writes to its repository, one at a time. */
+  serially<T>(write: () => Promise<T>): Promise<T>;
+  /**
+   * Fast-forwards the checkout to the host's `main` (`followBase`), one of the worker's writes
+   * (`serially`), as a change's deploy and a push to `main` do first; on a new revision, how far
+   * each app taken from a source is behind it is checked again, in the background, into the
+   * runtime's table (`recordAppsBehind` in worker.ts), as at the worker's start.
+   */
+  followMain(): Promise<{ revision: string } | { skipped: string } | { error: string }>;
+  /** The runtime's tables (`db.ts`): what the worker writes for the app to read, such as a sandbox run's checks. */
+  db(): Promise<Db>;
   types: ReadonlyMap<string, Resource>;
   /** The objects the data files declare, read at each call: a workflow's change operation may not aim at one (`refuseDeclared`). */
   declaredObjects(): Promise<DeclaredObjects>;
@@ -88,6 +109,11 @@ export interface WorkerState {
   stopped: boolean;
   /** Which of its runs are executing and which wait, until when: what the worker's `idle` reads. */
   deadlines: DeadlineRegistry;
+  /**
+   * Aborted once the worker has stopped, after DBOS is down: what work of its that outlives a DBOS
+   * call stops on (a chat turn's agent, the check of the apps behind), recorded nowhere.
+   */
+  shutdown: AbortSignal;
 }
 
 /** What a run keeps in memory. Rebuilt the same way when DBOS replays the run. */
@@ -136,3 +162,18 @@ export interface WorkflowOutline {
  * it, whether it is a sandbox run, the worker's source and policy), as no `ctx` member gives them.
  */
 export const currentRun = new AsyncLocalStorage<Run>();
+
+/** The run whose built-in step is running (`currentRun`): `what` names the step for the error when there is none. */
+export function runNow(what: string): Run {
+  const run = currentRun.getStore();
+  if (!run) throw new Error(`${what} ran outside its run`);
+  return run;
+}
+
+/**
+ * A sandbox run's checks recorded for the app (`recordChecks`, which never throws); nothing for a
+ * live run, which never loads `sandbox.ts`, and with it Cucumber.
+ */
+export async function recordSandboxChecks(run: Run): Promise<void> {
+  if (run.sandbox !== undefined) await (await import("./sandbox.ts")).recordChecks(run, run.sandbox);
+}

package/src/sandbox.ts

@@ -9,8 +9,10 @@ import { entry, type LedgerRecord, write } from "./ledger.ts";
 import type { DriverFn } from "./op.ts";
 import type { Run } from "./run.ts";
 import { memorySecrets } from "./secret.ts";
-import { type Given, loadScenarios, type Scenario } from "./scenario.ts";
-import { errorMessage } from "./shared.ts";
+import { writeRunChecks } from "./db.ts";
+import { warn } from "./log.ts";
+import { check, type Given, loadScenarios, type RunChecks, type Scenario } from "./scenario.ts";
+import { errorMessage, notLoaded } from "./shared.ts";
 
 /*
  * What a worker does for a sandbox run, imported only when it starts one: kept apart from
@@ -125,8 +127,9 @@ export async function seedSandbox(run: Run, name: string, input: unknown): Promi
       const { scenarios, errors } = await loadScenarios(state);
       const scenario = scenarios.find((s) => s.name === name);
       if (!scenario) {
-        const why = errors.length ? `; these files did not load: ${errors.map((e) => e.message).join("; ")}` : "";
-        throw new SanomaError("invalid_input", `No scenario named "${name}"${why}`, { scenario: name });
+        throw new SanomaError("invalid_input", `No scenario named "${name}"${notLoaded(errors)}`, {
+          scenario: name,
+        });
       }
       if (scenario.workflow !== run.workflow) {
         throw new SanomaError("invalid_input", `Scenario "${name}" runs ${scenario.workflow}, not ${run.workflow}`, {
@@ -214,3 +217,37 @@ export async function seedSandbox(run: Run, name: string, input: unknown): Promi
   run.fakeSecrets = secrets;
   await write(run, entry(run, { type: "scenario.seeded", scenario: name, seeds }));
 }
+
+/**
+ * A seeded sandbox run's checks against its ledger so far, written for the app (`writeRunChecks`):
+ * Cucumber runs its scenario's Then steps over the feature file as it reads now, which the agent
+ * may have changed since. Called when the run waits and when it ends (`recordSandboxChecks`); a
+ * check met is settled when what it expects stays so (a call made, a decision recorded), and every
+ * one once the run has ended, which the app reads from the run's status. No step and no ledger
+ * record, so a replay neither depends on it nor differs by it: a failure is warned about, and the
+ * run goes on.
+ */
+export async function recordChecks(run: Run, name: string): Promise<void> {
+  if (!run.fakeDrivers) return;
+  const { state } = run;
+  try {
+    const checks = await checksOf(run, name).catch((err: unknown): RunChecks => ({ error: errorMessage(err) }));
+    await writeRunChecks(await state.db(), run.id, checks);
+  } catch (err) {
+    warn(`run ${run.id}: could not record its checks against scenario "${name}": ${errorMessage(err)}`);
+  }
+}
+
+async function checksOf({ id, state }: Run, name: string): Promise<RunChecks> {
+  const loaded = await loadScenarios(state);
+  const scenario = loaded.scenarios.find((s) => s.name === name);
+  if (!scenario) return { error: `The feature files no longer have scenario "${name}"${notLoaded(loaded.errors)}` };
+  const checks = await check(state, scenario, await state.ledger.read(id));
+  return {
+    checks: checks.map((c, i) => {
+      const e = scenario.expect[i]!;
+      // Met once: a call made, or a decision recorded, stays made. Every one is, once the run has ended (`runDetail`).
+      return { ...c, settled: c.ok && (("called" in e && e.called === true) || "decision" in e) };
+    }),
+  };
+}

package/src/scenario.ts

@@ -186,6 +186,23 @@ export interface Check {
   detail?: string;
 }
 
+/** One of a sandbox run's checks, and whether its answer is final. */
+export interface RunCheck extends Check {
+  /**
+   * True once the answer cannot change: the run has ended, or the check expects a call that
+   * has been made (or a decision recorded). Until then a check not met is not failed yet, and
+   * one met (a call not made so far) may still fail.
+   */
+  settled: boolean;
+}
+
+/**
+ * A sandbox run's checks, as the worker ran them when the run last waited or ended (`recordChecks`):
+ * each of its scenario's expectations against its ledger, or why there are none (its scenario is
+ * no longer in the feature files, with those that did not load, or they could not be read at all).
+ */
+export type RunChecks = { checks: RunCheck[] } | { error: string };
+
 /**
  * What steps can name: the config's operations, workflows, resource types and collections by id,
  * the steps its connectors (and the company) ship, where the feature files are, and the root

package/src/seal.ts

@@ -2,8 +2,9 @@ import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import { deriveSigningKey, signingKeyFor } from "./deployment-key.ts";
 
 // Small values sealed under a key of their own, derived from the deployment's SANOMA_SIGNING_KEY
-// for one purpose (HKDF-SHA256): a sign-in code in a `login-code` run's input, and a request for
-// an invite that a holder of the key sends to the instance (`POST /auth/invite`). AES-256-GCM, the
+// for one purpose (HKDF-SHA256): a sign-in code in a `login-code` run's input, a code a person
+// pastes back to their own agent's sign-in, in the message to their chat turn's run, and a request
+// for an invite that a holder of the key sends to the instance (`POST /auth/invite`). AES-256-GCM, the
 // purpose as its additional data, so a value sealed for one purpose never opens for another.
 
 const IV = 12;
@@ -40,6 +41,7 @@ function unseal(purpose: string, sealed: string): unknown {
 }
 
 const CODE = "login code";
+const CHAT_CODE = "chat code";
 const INVITE = "invite request";
 
 /**
@@ -57,6 +59,18 @@ export function openLoginCode(sealed: string, to: string): string {
   return opened.code;
 }
 
+/**
+ * A code a person pastes for their own agent's sign-in, sealed for the chat turn's run `runId`
+ * (`SanomaClient.turnCode`), so the run's messages, which DBOS keeps, never show it.
+ */
+export const sealChatCode = (runId: string, code: string): string => seal(CHAT_CODE, { runId, code });
+
+/** The code `sealChatCode` sealed for `runId`; undefined for anything else, a code sealed for another run among it. */
+export function openChatCode(sealed: string, runId: string): string | undefined {
+  const opened = unseal(CHAT_CODE, sealed) as { runId?: unknown; code?: unknown } | undefined;
+  return typeof opened?.code === "string" && opened.runId === runId ? opened.code : undefined;
+}
+
 /** A request for an invite (`POST /auth/invite { request }`): for whom, until when (ms since the epoch), and a nonce. */
 export interface InviteRequest {
   email: string;