@sanoma-ai/workflows 0.11.14 → 0.11.16

package/src/chat-workflow.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { defineWorkflow, type WorkflowDefinition } from "./define.ts";
+import { type CHAT_WORKFLOW, DRAFT_ID } from "./shared.ts";
+
+// The built-in `chat` workflow: a turn of a person's chat with the operator agent, run by the
+// worker, where the agent's harness can run its children in the chat's draft. The app starts it
+// (`SanomaClient.startTurn`, as the chat's person, one run per message) and streams the reply the
+// turn writes to the database; a new message or a pasted sign-in code reaches the run as a message
+// (`ChatTell`). What the turn does is the app's (`AppSteps.chat`), in a step of `chat-steps.ts`; a
+// workflow like any other, held to the same lint.
+
+/**
+ * A turn's input: the chat, the id of the person's new message, which the app wrote to the chat's
+ * transcript before it started the turn, and the chat's turn before it, which this one waits for.
+ * Ids only: a run's input and output are in its ledger, which the company's staff read, and a
+ * chat's text is its person's (`Chats`).
+ */
+export const ChatTurnInput = z.object({
+  chat: z.string().regex(DRAFT_ID, "a chat id is letters, digits, _ and -"),
+  message: z.string().regex(DRAFT_ID, "a message id is letters, digits, _ and -"),
+  after: z.string().min(1).optional(),
+});
+export type ChatTurnInput = z.infer<typeof ChatTurnInput>;
+
+/** What a turn answers: the reply's message id (never its text), once it wrote one; `interrupted` for a turn the worker's restart cut short. */
+export interface ChatTurnOutput {
+  reply?: string;
+  interrupted?: true;
+}
+
+/** What a turn's run is told (`CHAT_TOPIC`): stop (a new message came), a sign-in code sealed for the run, its turn's end. */
+export const ChatTell = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("stop") }),
+  z.object({ kind: z.literal("code"), sealed: z.string().min(1) }),
+  z.object({ kind: z.literal("ended") }),
+]);
+export type ChatTell = z.infer<typeof ChatTell>;
+
+/** What a chat turn does, each part a step or a wait of its own (`chat-steps.ts`). */
+export interface ChatSteps {
+  /** Waits for the chat's turn before this one to end, however it ends: its reply is in the transcript then. */
+  after(runId: string): Promise<void>;
+  /**
+   * The turn, a step that runs while the run reads what it is told (`tell`), and tells the run when
+   * it ends. Throws at once, not rejecting, when the worker runs no agent.
+   */
+  turn(input: ChatTurnInput): Promise<ChatTurnOutput>;
+  /** The next thing the run is told, handed to the turn under way: false once the turn has ended. */
+  tell(): Promise<boolean>;
+}
+
+/** The built-in chat workflow over `steps`: `resolveConfig` adds it to every config. */
+export function chatWorkflow(steps: ChatSteps): 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: "chat" satisfies typeof CHAT_WORKFLOW,
+    title: "A chat turn",
+    trigger: "manual",
+    input: ChatTurnInput,
+    uses: [],
+    run: async (_ctx, input): Promise<ChatTurnOutput> => {
+      if (input.after !== undefined) await steps.after(input.after);
+      const turn = steps.turn(input);
+      let open = true;
+      while (open) open = await steps.tell();
+      return turn;
+    },
+  });
+}

package/src/chats.ts

@@ -1,13 +1,15 @@
-import type { UIMessage } from "ai";
-import { asc, desc, eq, sql } from "drizzle-orm";
+import type { UIMessage, UIMessageChunk } from "ai";
+import { and, asc, desc, eq, gt, ne, sql } from "drizzle-orm";
 import type { Db } from "./db.ts";
-import { chatMessages, chats } from "./db/company.ts";
+import { chatChunks, chatMessages, chats } from "./db/company.ts";
 import { SanomaError } from "./errors.ts";
 
 // The operator agent's chats, in the config's database beside the runtime's other tables: one row
-// per chat (whose it is, the engine it runs on, the draft it edits) and its messages as the AI
-// SDK's UI messages. The turn itself is not durable: what a restart keeps is this transcript and
-// the draft's branch, and the person sends "continue".
+// per chat (whose it is, the engine it runs on, the draft it edits, the turn last begun), its
+// messages as the AI SDK's UI messages, and the reply its turn streams, as chunks. A turn is a run
+// of `chat` the worker executes: it writes the transcript and the chunks, which the app reads. A
+// worker's restart does not run a turn again: the transcript and the draft's branch are what it
+// keeps, and the person sends "continue".
 
 /** A chat as `SanomaClient.chats.list` reads it. */
 export interface Chat {
@@ -33,20 +35,36 @@ export interface Chats {
   /** Records the draft the chat edits. */
   attach(id: string, draftId: string): Promise<void>;
   /**
-   * Writes these messages of the chat, each by its id: a message already there is replaced in its
-   * place, a new one goes after the rest, in the order given.
+   * Writes these messages of the chat, each by its id: a new one goes after the rest, in the order
+   * given, and one already there is replaced in its place, or, with `last`, moved after the rest too.
    */
-  upsert(id: string, messages: readonly UIMessage[]): Promise<void>;
+  upsert(id: string, messages: readonly UIMessage[], options?: { last?: boolean }): Promise<void>;
   /** The chat's messages in order; none for a chat that has none. */
   load(id: string): Promise<UIMessage[]>;
+  /** Whether the chat `id` has a message `message`. */
+  has(id: string, message: string): Promise<boolean>;
   /** The chat `id`, or undefined when there is none. */
   get(id: string): Promise<Chat | undefined>;
   /** The person's chats, the newest first: the latest 50. */
   list(person: string): Promise<Chat[]>;
+  /**
+   * Begins the turn `turn` (its run's id) of the chat `id`: false when it had begun already (the
+   * worker restarted under it). The chunks of the chat's other turns go.
+   */
+  begin(id: string, turn: string): Promise<boolean>;
+  /** Writes these chunks of the reply the turn `turn` of the chat `id` streams, after those written. */
+  append(id: string, turn: string, chunks: readonly UIMessageChunk[]): Promise<void>;
+  /** Ends the turn's stream: nothing is appended after it. */
+  end(id: string, turn: string): Promise<void>;
+  /** The turn's chunks after the one numbered `after` (0 for all), the last one's number, and whether its stream has ended. */
+  chunks(turn: string, after: number): Promise<{ chunks: UIMessageChunk[]; last: number; ended: boolean }>;
 }
 
-const chatOf = ({ draftId, createdAt, ...row }: typeof chats.$inferSelect): Chat => ({
-  ...row,
+const chatOf = ({ id, person, engine, title, draftId, createdAt }: typeof chats.$inferSelect): Chat => ({
+  id,
+  person,
+  engine,
+  title,
   ...(draftId === null ? {} : { draftId }),
   createdAt: createdAt.getTime(),
 });
@@ -67,10 +85,10 @@ export function chatStore(db: () => Promise<Db>): Chats {
     async attach(id, draftId) {
       await (await db()).update(chats).set({ draftId }).where(eq(chats.id, id));
     },
-    async upsert(id, messages) {
+    async upsert(id, messages, options) {
       if (!messages.length) return;
       if (messages.some((m) => !m.id)) throw new SanomaError("invalid_input", "A chat message needs an id");
-      // A new message's place is after the chat's last, in the order given.
+      // A new message's place, or a moved one's, is after the chat's last, in the order given.
       const last = sql`(SELECT coalesce(max(${chatMessages.seq}), 0) FROM ${chatMessages} WHERE ${eq(chatMessages.chatId, id)})`;
       await (
         await db()
@@ -81,7 +99,7 @@ export function chatStore(db: () => Promise<Db>): Chats {
         )
         .onConflictDoUpdate({
           target: [chatMessages.chatId, chatMessages.id],
-          set: { message: sql`excluded.message` },
+          set: { message: sql`excluded.message`, ...(options?.last && { seq: sql`excluded.seq` }) },
         });
     },
     async load(id) {
@@ -94,10 +112,49 @@ export function chatStore(db: () => Promise<Db>): Chats {
         .orderBy(asc(chatMessages.seq), asc(chatMessages.id));
       return rows.map((row) => row.message);
     },
+    async has(id, message) {
+      const [row] = await (
+        await db()
+      )
+        .select({ id: chatMessages.id })
+        .from(chatMessages)
+        .where(and(eq(chatMessages.chatId, id), eq(chatMessages.id, message)));
+      return row !== undefined;
+    },
     async get(id) {
       const [row] = await (await db()).select().from(chats).where(eq(chats.id, id));
       return row && chatOf(row);
     },
+    async begin(id, turn) {
+      const database = await db();
+      const begun = await database
+        .update(chats)
+        .set({ turn })
+        .where(and(eq(chats.id, id), sql`${chats.turn} IS DISTINCT FROM ${turn}`))
+        .returning({ id: chats.id });
+      await database.delete(chatChunks).where(and(eq(chatChunks.chatId, id), ne(chatChunks.runId, turn)));
+      return begun.length > 0;
+    },
+    async append(id, turn, chunks) {
+      if (chunks.length) await appendChunks(await db(), id, turn, chunks);
+    },
+    async end(id, turn) {
+      await appendChunks(await db(), id, turn, [null]);
+    },
+    async chunks(turn, after) {
+      const rows = await (
+        await db()
+      )
+        .select({ seq: chatChunks.seq, chunk: chatChunks.chunk })
+        .from(chatChunks)
+        .where(and(eq(chatChunks.runId, turn), gt(chatChunks.seq, after)))
+        .orderBy(asc(chatChunks.seq));
+      return {
+        chunks: rows.flatMap((row) => (row.chunk === null ? [] : [row.chunk])),
+        last: rows.at(-1)?.seq ?? after,
+        ended: rows.at(-1)?.chunk === null,
+      };
+    },
     async list(person) {
       const rows = await (
         await db()
@@ -111,3 +168,12 @@ export function chatStore(db: () => Promise<Db>): Chats {
     },
   };
 }
+
+/** Writes `chunks` (null, the end) after the turn's last, in the order given. */
+async function appendChunks(db: Db, id: string, turn: string, chunks: readonly (UIMessageChunk | null)[]) {
+  // A chunk's place is after the turn's last, in the order given.
+  const last = sql`(SELECT coalesce(max(${chatChunks.seq}), 0) FROM ${chatChunks} WHERE ${eq(chatChunks.runId, turn)})`;
+  await db
+    .insert(chatChunks)
+    .values(chunks.map((chunk, n) => ({ chatId: id, runId: turn, seq: sql<number>`${last} + ${n + 1}`, chunk })));
+}

package/src/client.ts

@@ -32,21 +32,26 @@ import { type Tokens, tokenStore } from "./tokens.ts";
 import { collectionsDriver } from "./collection.ts";
 import { type ResolvedConfig, resolveConfig, type SanomaConfig } from "./config.ts";
 import { configuredSecrets } from "./credentials.ts";
-import { dbosClient, lazyDb, type LazyDb, spendInviteRequest } from "./db.ts";
+import {
+  type AppBehind,
+  dbosClient,
+  lazyDb,
+  type LazyDb,
+  readAppBehind,
+  readRunChecks,
+  spendInviteRequest,
+} from "./db.ts";
 import { type CredentialStatus, credentialsOf } from "./env.ts";
 import { type ApprovalState, Principal, type WorkflowDefinition } from "./define.ts";
 import { APPLY_WORKFLOW, type ApplyInput, type ApplyReport } from "./apply.ts";
 import {
   ADMIN,
-  BASE,
   type ChangeEvent,
   ChangeEventSchema,
   ChangeInput,
   type ChangeReport,
   type ChangeState,
-  followBase,
   initialChangeState,
-  repositoryOf,
 } from "./change.ts";
 import { DRIFT_WORKFLOW, type DriftReport } from "./drift.ts";
 import { isDirect } from "./direct.ts";
@@ -59,7 +64,6 @@ import {
   parseOrThrow,
   PolicyDeniedError,
   SanomaError,
-  vendorCodeOf,
 } from "./errors.ts";
 import {
   insertRecord,
@@ -70,7 +74,6 @@ import {
   type OwnedLedger,
   ownedLedger,
 } from "./ledger.ts";
-import { warn } from "./log.ts";
 import type { CallContext, Driver, Op, SignInMethod } from "./op.ts";
 import { allowAll, type RecordedDecision } from "./policy.ts";
 import { admit, readPeople } from "./resources.ts";
@@ -83,10 +86,16 @@ import {
   CHANGE_MERGE,
   CHANGE_TOPIC,
   CHANGE_WORKFLOW,
+  CHAT_TOPIC,
+  CHAT_WORKFLOW,
   changeIdOf,
+  chatRunId,
+  chatRunPrefix,
   DATA_VENDOR,
+  DRAFT_ID,
   ENDED_STATUSES,
   errorMessage,
+  FOLLOW_WORKFLOW,
   HOST_CHECK_AGENT,
   isEnded,
   isToken,
@@ -96,14 +105,11 @@ import {
   SCHEDULE_AGENT,
   WORKFLOW_ACTION,
 } from "./shared.ts";
-import { draftOf, type RemoteEvent, type RepoRef, type Source } from "./source.ts";
-
-/** The company's repository on its host, for `remoteEvent`. */
-type Repository = Awaited<ReturnType<typeof repositoryOf>>;
-
-/** 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();
+import { RemoteEventSchema } from "./follow-workflow.ts";
+import type { ChatTell, ChatTurnInput } from "./chat-workflow.ts";
+import { sealChatCode } from "./seal.ts";
+import type { RunChecks } from "./scenario.ts";
+import type { RemoteEvent } from "./source.ts";
 
 /** A principal, or its id alone. */
 const PrincipalOrId = z.union([
@@ -260,11 +266,6 @@ export interface ClientOptions {
    * runs a worker that stops when idle starts it again with it (`Supervisor.resume`). Must not throw.
    */
   onWrite?: () => void;
-  /**
-   * The company's repository, as the worker is given it: what `remoteEvent` acts for (its
-   * `origin`) and fetches a draft's new commits into. Without one, `remoteEvent` does nothing.
-   */
-  source?: Source;
   /**
    * The version each run it starts is queued for, so only a worker of that code runs it: the app
    * bundle's (its snapshot's), which is live beside a worker of another version while a deploy
@@ -365,10 +366,12 @@ export class SanomaClient {
       options.sandbox,
       "`sandbox` must be the name of a scenario in the config's `scenarios/`",
     );
-    if (workflow.name === CHANGE_WORKFLOW && !isChangeRunOf((parsed as ChangeInput).id, runId)) {
-      throw new SanomaError("invalid_input", "A change is started with openChange, which names its run", { runId });
-    }
     const hold = await this.startHold(workflow.name, parsed, startedBy, runId);
+    const own = OWN_STARTS[workflow.name];
+    if (own && !(await own.admits(parsed, startedBy, runId, this))) {
+      const refused = `A run of ${workflow.name} is started with ${own.by}, which names its run`;
+      throw new SanomaError("invalid_input", refused, { runId });
+    }
     const args: RunArgs = { input, startedBy, ...(sandbox === undefined ? {} : { sandbox }), ...(hold && { hold }) };
     // Kept on the run's status row too, so a listing tells sandbox runs apart without its input,
     // and says whom an agent's run is for (DBOS keeps the principal's id and groups itself); a
@@ -414,7 +417,9 @@ export class SanomaClient {
    * The policy's answer to starting a run of `workflow` as `startedBy` (`decideStart`), for a
    * workflow of the config's own: a deny throws `policy_denied`; a hold is what the run waits on
    * before its body. A run `runId` names already is returned as it is, whatever the policy says now, but to a visitor.
-   * A visitor (`isVisitor`) starts no built-in but `call`, whose calls the policy decides as direct ones.
+   * A visitor (`isVisitor`, an api token's principal too) starts no built-in but `call`, whose calls
+   * the policy decides as direct ones: the app's own actions on the repository (`app-workflows.ts`)
+   * are staff's, as their server functions were, which no site's host answered.
    */
   private async startHold(
     workflow: string,
@@ -976,6 +981,24 @@ export class SanomaClient {
     return Promise.all(rows.map((row) => this.changeView(row)));
   }
 
+  /**
+   * Whether a change is merging or deploying `main` now (`ChangeState.phase`, as its run last
+   * published it), which follows `main` and applies the hosts itself.
+   */
+  async changeDeploying(): Promise<boolean> {
+    const rows = await this.dbos.listWorkflows({
+      workflowName: CHANGE_WORKFLOW,
+      applicationName: this.config.appName,
+      status: dbosStatusesOf("queued", "running"),
+      loadInput: false,
+      loadOutput: false,
+    });
+    const phases = await Promise.all(
+      rows.map(async (row) => (await this.dbos.getEvent<ChangeState>(row.workflowID, CHANGE_EVENT, 0))?.phase),
+    );
+    return phases.some((phase) => phase === "merging" || phase === "deploying");
+  }
+
   /** The change of the draft `id`: its latest run's (`openChange`), or undefined when it has none. */
   async change(id: string): Promise<ChangeView | undefined> {
     const [row] = await this.changeRuns(id, { load: true });
@@ -1025,105 +1048,86 @@ export class SanomaClient {
   }
 
   /**
-   * Does what a host's webhook says happened (`RemoteEvent`, from a remote half's `webhook`) to the
-   * company's repository, the `origin` of `ClientOptions.source` (`repositoryOf`); an event of
-   * another repository, or with no source, is ignored. A delivery told again does nothing more.
-   *
-   * - `pushed` to `main`: the checkout follows `main`, then apply on the declared hosts
-   *   (`ResolvedConfig.hosts`) as `host-check`, as the run `deploy:<head>`, once per head; nothing
-   *   with no host, nor while a change is merging or deploying, which does both itself.
-   * - `pushed` to a draft's branch (`draftOf`) with its change open: the host's commits fetched into
-   *   the draft (`Source.follow` on its branch), then the change told `commits`, as `by`; nothing
-   *   when the change or the draft is at that head already (the run's own push), or when the draft
-   *   cannot fast-forward to it (warned).
-   * - `closed` for the open change's pull request: the change told `merged` (with its merge commit)
-   *   or `closed`, as `by`. The run checks either on the host before it believes it.
+   * Starts the built-in follow workflow on what a host's webhook says happened (`RemoteEvent`,
+   * from a remote half's `webhook`, verified), as the runtime's agent `host-check`: the worker,
+   * which has the checkout, follows it there (`follow-workflow.ts`). Its run id is
+   * `follow:<sha256 of the event>`, so a delivery told again is the one run. Its id.
    */
-  async remoteEvent(event: RemoteEvent, options: { by: Principal | string }): Promise<void> {
-    const main = event.kind === "pushed" && event.branch === BASE;
-    const id = draftOf(event.branch);
-    if (!main && id === undefined) return;
-    const repository = await this.repository();
-    if (!repository || !sameRepo(repository.repo, event.repo)) return;
-    if (main) return this.deployPush(repository, event.head);
-    const change = await this.change(id!);
-    if (!change || isEnded(change.status)) return;
-    let told: ChangeEvent;
-    let key: string;
-    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;
-      told = event.merged && event.sha !== undefined ? { kind: "merged", sha: event.sha } : { kind: "closed" };
-      key = `${event.number}:${event.sha ?? "closed"}`;
-    } else {
-      if (change.state.head === event.head || !(await this.fetched(repository, event.branch, event.head))) return;
-      told = { kind: "commits" };
-      key = event.head;
-    }
-    await this.changeEvent(id!, told, { by: options.by, key: `${event.kind}:${event.branch}:${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;
-      },
-    );
+  async follow(event: RemoteEvent): Promise<string> {
+    const parsed = parseOrThrow(RemoteEventSchema, event, "Not an event of a host's webhook");
+    return this.start(FOLLOW_WORKFLOW, parsed, { startedBy: HOST_CHECK_AGENT, runId: followRunId(parsed) });
   }
 
-  /** After a push of `head` to `main` (`remoteEvent`): the checkout follows it, then apply on the declared hosts. */
-  private async deployPush({ source }: Repository, head: string): Promise<void> {
-    const runId = `deploy:${head}`;
-    const [deployed, phases] = await Promise.all([this.run(runId), this.openChangePhases()]);
-    if (deployed || phases.some((phase) => phase === "merging" || phase === "deploying")) return;
-    // First, as a change's deploy does: the hosts, and what apply reads, are then main's.
-    const moved = await followBase(this.config.remotes, this.storedSecrets, source);
-    if (!("revision" in moved)) {
-      // Not on stale files, and nothing recorded as `deploy:<head>`: a redelivery may deploy it.
-      warn(
-        `${BASE} was not deployed: the checkout did not follow it: ${"skipped" in moved ? moved.skipped : moved.error}`,
-      );
-      return;
+  /**
+   * Starts a turn of the chat `input.chat` on the person's new message `input.message`, already in
+   * its transcript (`chats.upsert`), as `startedBy`, the chat's person: the built-in chat workflow,
+   * as the run `chat:<chat>:<message>` (`chatRunId`), after the chat's turn before it, which it
+   * waits for; that turn, when it has not ended, is told to stop. The worker runs the turn and
+   * writes its reply (`chats.chunks`, then the transcript). Its run id.
+   */
+  async startTurn(input: Omit<ChatTurnInput, "after">, options: StartOptions): Promise<string> {
+    const runId = chatRunId(input.chat, input.message);
+    // The latest other than this one, which a start told again finds first.
+    const before = (await this.turns(input.chat, 2)).find((row) => row.workflowID !== runId);
+    await this.start(CHAT_WORKFLOW, { ...input, ...(before && { after: before.workflowID }) } satisfies ChatTurnInput, {
+      ...options,
+      runId,
+    });
+    // Once the new turn stands, which refused anyone but the chat's person.
+    if (before && !isEnded(runStatus(before.status, []))) {
+      await this.dbos.send(before.workflowID, { kind: "stop" } satisfies ChatTell, CHAT_TOPIC);
     }
-    const hosts = await this.config.hosts();
-    if (hosts.length) await this.apply({ only: hosts }, { startedBy: HOST_CHECK_AGENT, runId });
+    return runId;
   }
 
-  /** Where each open change is (`ChangeState.phase`), read from what its run last published. */
-  private async openChangePhases(): Promise<(ChangeState["phase"] | undefined)[]> {
-    const rows = await this.dbos.listWorkflows({
-      workflowName: CHANGE_WORKFLOW,
-      applicationName: this.config.appName,
-      status: dbosStatusesOf("queued", "running"),
-      loadInput: false,
-      loadOutput: false,
-    });
-    return Promise.all(
-      rows.map(async (r) => (await this.dbos.getEvent<ChangeState>(r.workflowID, CHANGE_EVENT, 0))?.phase),
-    );
+  /** The chat's latest turn (`startTurn`), or undefined when it has had none. */
+  async turn(chat: string): Promise<RunSummary | undefined> {
+    const [row] = await this.turns(chat, 1);
+    return row && this.summarize(row);
   }
 
   /**
-   * Brings `head`, pushed to the draft's `branch` on the host, into the draft: false when it holds
-   * it already, or cannot take it (no `follow`, a commit of its own, or one uncommitted: warned).
+   * Hands `code`, which the person pasted on their own agent's sign-in card, to the sign-in waiting
+   * in the turn under way of their chat `chat`, sealed (`sealChatCode`), so the run's messages never
+   * show it. `run_not_found` when the chat has no turn under way of `by`'s.
    */
-  private async fetched({ source, url, host }: Repository, branch: string, head: string): Promise<boolean> {
-    const local = await Promise.resolve(source.head(branch)).catch(() => undefined);
-    if (local === head) return false;
-    const moved = source.follow
-      ? await source.follow({ url, token: await host.token(), ref: branch })
-      : { skipped: "this repository cannot follow its remote" };
-    if ("skipped" in moved) {
-      warn(`${branch} did not take the host's commits: ${moved.skipped}`);
-      return false;
+  async turnCode(chat: string, code: string, options: { by: Principal | string }): Promise<void> {
+    const by = await this.admitted(
+      parseOrThrow(PrincipalOrId, options?.by, '`by` must be a principal, such as "alice" or { id: "alice" }'),
+    );
+    const [row] = await this.turns(chat, 1);
+    if (!row || isEnded(runStatus(row.status, [])) || row.authenticatedUser !== by.id) {
+      throw new SanomaError("run_not_found", `No turn of chat ${chat} is under way`, { chat });
     }
-    return true;
+    const told: ChatTell = { kind: "code", sealed: sealChatCode(row.workflowID, code) };
+    await this.dbos.send(row.workflowID, told, CHAT_TOPIC);
+  }
+
+  /**
+   * How far the app `folder` (taken from a source) is behind its source, or why that cannot be
+   * told, as the worker last checked (at its start and after the checkout follows `main`);
+   * undefined when it has not told it.
+   */
+  async appBehind(folder: string): Promise<AppBehind | undefined> {
+    return readAppBehind(await this.database.db(), folder);
   }
 
-  /** The repository of `ClientOptions.source` on its host (`repositoryOf`); undefined with no source, remote or half for it. */
-  private async repository(): Promise<Repository | undefined> {
-    const { source } = this.options;
-    if (!source) return undefined;
-    return repositoryOf(this.config.remotes, this.storedSecrets, source).catch((err: unknown) => {
-      if (["no_remote", "no_remote_half"].includes(vendorCodeOf(err) ?? "")) return undefined;
-      throw err;
+  /** A sandbox run's checks against its scenario as the worker last ran them (when the run last waited or ended); undefined for none yet. */
+  async runChecks(runId: string): Promise<RunChecks | undefined> {
+    return readRunChecks(await this.database.db(), runId);
+  }
+
+  /** The latest `limit` turns of the chat `chat`, newest first: its runs `chat:<chat>:<message>` (`chatRunPrefix`). */
+  private async turns(chat: string, limit: number) {
+    return this.dbos.listWorkflows({
+      // DBOS matches the prefix with LIKE as given, where a chat id's `_` is any character: escaped.
+      workflow_id_prefix: chatRunPrefix(chat).replaceAll(/[\\%_]/g, "\\$&"),
+      workflowName: CHAT_WORKFLOW,
+      applicationName: this.config.appName,
+      sortDesc: true,
+      limit,
+      loadInput: false,
+      loadOutput: false,
     });
   }
 
@@ -1687,6 +1691,47 @@ const alreadyDecided = (runId: string, a: ApprovalState) =>
     },
   );
 
+/**
+ * The built-ins only one of the client's methods starts, by name: that method (`by`), and whether
+ * a start is its own (`admits`), which `start` asks once the policy has (a visitor is denied
+ * first), refusing any other: a change under the id `openChange` names; a follow as `host-check`
+ * under its event's id; a chat turn under its chat's and message's id, after a turn of the same
+ * chat, as the chat's person.
+ */
+const OWN_STARTS: Record<
+  string,
+  {
+    by: string;
+    admits(
+      input: any,
+      startedBy: Principal,
+      runId: string | undefined,
+      client: SanomaClient,
+    ): boolean | Promise<boolean>;
+  }
+> = {
+  [CHANGE_WORKFLOW]: { by: "openChange", admits: (input: ChangeInput, _by, runId) => isChangeRunOf(input.id, runId) },
+  [FOLLOW_WORKFLOW]: {
+    by: "follow",
+    admits: (event: RemoteEvent, by, runId) => runId === followRunId(event) && by.id === HOST_CHECK_AGENT,
+  },
+  [CHAT_WORKFLOW]: {
+    by: "startTurn",
+    admits: async ({ chat, message, after }: ChatTurnInput, by, runId, client) =>
+      runId === chatRunId(chat, message) &&
+      (after === undefined ||
+        (after.startsWith(chatRunPrefix(chat)) && DRAFT_ID.test(after.slice(chatRunPrefix(chat).length)))) &&
+      (await client.chats.get(chat))?.person === by.id,
+  },
+};
+
+/**
+ * A follow's run id (`SanomaClient.follow`): `follow:` and the SHA-256 of the event as its schema
+ * parsed it, its keys then in the schema's order, so one event is one id however its JSON was laid out.
+ */
+const followRunId = (parsed: RemoteEvent) =>
+  `follow:${createHash("sha256").update(JSON.stringify(parsed)).digest("hex")}`;
+
 /** A change's first run's id: `change:<draft id>`. */
 const changeRunId = (id: string) => `change:${id}`;
 

package/src/config.ts

@@ -26,8 +26,14 @@ import { type ApplyDeclared, applyWorkflow } from "./apply.ts";
 import { applySteps } from "./apply-steps.ts";
 import { callWorkflow } from "./call-workflow.ts";
 import { changeDriver, changeOps, reservedFor } from "./change.ts";
+import { appRunner } from "./app-steps.ts";
+import { appWorkflows } from "./app-workflows.ts";
 import { changeSteps } from "./change-steps.ts";
 import { changeWorkflow } from "./change-workflow.ts";
+import { chatSteps } from "./chat-steps.ts";
+import { chatWorkflow } from "./chat-workflow.ts";
+import { followSteps } from "./follow-steps.ts";
+import { followWorkflow } from "./follow-workflow.ts";
 import {
   type Collection,
   collectionsConnector,
@@ -68,7 +74,9 @@ import {
   BUILT_IN_WORKFLOWS,
   CALL_WORKFLOW,
   CHANGE_WORKFLOW,
+  CHAT_WORKFLOW,
   DATA_VENDOR,
+  FOLLOW_WORKFLOW,
   LOGIN_CODE_WORKFLOW,
 } from "./shared.ts";
 import { fakeSourceDriver, type RemoteHalf, SOURCE_RESOLVE, sourceDriver, sourceOps } from "./source.ts";
@@ -445,6 +453,12 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
       .map((r) => r.id);
   };
   names.set(CHANGE_WORKFLOW, changeWorkflow(changeOps, changeSteps({ remotes, hosts })));
+  // Built-in, in every config: what a git host's webhook says happened, which the worker with the checkout follows.
+  names.set(FOLLOW_WORKFLOW, followWorkflow(followSteps({ remotes, hosts })));
+  // Built-in, in every config: the app's own actions on the repository, which a worker given the app's steps runs.
+  for (const wf of appWorkflows(appRunner)) names.set(wf.name, wf);
+  // Built-in, in every config: a chat turn, which a worker given the app's steps runs.
+  names.set(CHAT_WORKFLOW, chatWorkflow(chatSteps()));
   const declaredObjects = () => readDeclaredObjects(root, connectors, declarable);
   // Built-in: a direct call the policy holds for an approval, made a run, when any operation may be called directly.
   const call = callWorkflow(ops, drivers, types);