@sanoma-ai/workflows 0.11.15 → 0.11.17

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";
@@ -223,6 +231,12 @@ export interface ResolvedConfig {
    * declares a host type.
    */
   hosts(): Promise<string[]>;
+  /**
+   * The resources the data files under `root` declare whose type is a sandbox (`<file>#<export>`),
+   * read at each call: where a coding agent's boxes are opened. None when no connector declares a
+   * sandbox type.
+   */
+  sandboxes(): Promise<string[]>;
   /**
    * The objects the data files under `root` declare, read at each call: what a workflow's change
    * operation may not aim at, since only apply changes a declared object.
@@ -281,6 +295,47 @@ export function defineConfig(config: SanomaConfig): SanomaConfig {
   return { ...config, file: config.file ?? callerFile() };
 }
 
+/**
+ * Joins the declaration files' modules (`declarationFiles`, each by its path) to `config`, as
+ * `sanoma` loads it and the Worker's bundle composes it: a workflow file's default export is a
+ * workflow (`defineWorkflow`), a file without one a helper; each export of a data file is a
+ * collection. One the config lists already is kept, once. A `workflows` or `collections` that is
+ * no list is left for `resolveConfig` to explain. Throws naming the file for an export that is
+ * neither.
+ */
+export function joinDeclarations(
+  config: SanomaConfig,
+  modules: { workflows: [path: string, module: { default?: unknown }][]; data: [path: string, module: object][] },
+): void {
+  if (config.workflows === undefined || Array.isArray(config.workflows)) {
+    const workflows = new Set(config.workflows);
+    for (const [path, { default: wf }] of modules.workflows) {
+      if (wf === undefined) continue;
+      if ((wf as { kind?: unknown } | null)?.kind !== "workflow") {
+        throw new Error(
+          `${path}'s default export is not a workflow: a file of workflows/ exports one, \`export default defineWorkflow({ … })\`, or none (a helper the workflows import)`,
+        );
+      }
+      workflows.add(wf as WorkflowDefinition<any, any>);
+    }
+    if (workflows.size > 0) config.workflows = [...workflows];
+  }
+  if (config.collections === undefined || Array.isArray(config.collections)) {
+    const collections = new Set(config.collections);
+    for (const [path, module] of modules.data) {
+      for (const [name, value] of Object.entries(module)) {
+        if (!isCollection(value)) {
+          throw new Error(
+            `${path} exports ${name}, which is not a collection: resources/data.ts holds collections only, each \`export const ${name} = collection({ name, key, fields })\` with collection from "sanoma/data"`,
+          );
+        }
+        collections.add(value);
+      }
+    }
+    if (collections.size > 0) config.collections = [...collections];
+  }
+}
+
 export function resolveDatabaseUrl(config: { databaseUrl?: string }, env: NodeJS.ProcessEnv = process.env): string {
   return config.databaseUrl ?? env.SANOMA_DATABASE_URL ?? DEFAULT_DATABASE_URL;
 }
@@ -437,14 +492,21 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
     names.set(APPLY_WORKFLOW, applyWorkflow(types, ops, drivers, applySteps(appName, root, read)));
   }
   // Built-in, in every config: the life of a change, which deploys to the declared hosts after its merge.
-  // The declared hosts' ids, as the files say them: nothing derived, nothing minted.
-  const hosts = async () => {
+  // The declared hosts' (and sandboxes') ids, as the files say them: nothing derived, nothing minted.
+  const declaredOf = (contract: "host" | "sandbox") => async () => {
     const { loadDataFiles } = await import("./resources.ts");
     return loadDataFiles(root, connectors, declarable)
-      .resources.filter((r) => types.get(`${r.vendor}.${r.type}`)?.host)
+      .resources.filter((r) => types.get(`${r.vendor}.${r.type}`)?.[contract])
       .map((r) => r.id);
   };
+  const hosts = declaredOf("host");
   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);
@@ -480,6 +542,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
     models: makersOf(config.connectors, "model"),
     remotes,
     hosts,
+    sandboxes: declaredOf("sandbox"),
     declaredObjects,
     ...(scenarios && { scenarios }),
     types,

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/description.ts

@@ -298,10 +298,11 @@ export const VendorEntrySchema = z.strictObject({
 export type VendorEntry = z.infer<typeof VendorEntrySchema>;
 
 /**
- * The contracts a resource type meets, from its spec: `host`, `database` and `wakeup` (`Host`,
- * `Database`, `Wakeup`), and `source` for a type a host's `source` names (the repository it clones).
+ * The contracts a resource type meets, from its spec: `host`, `database`, `wakeup` and `sandbox`
+ * (`Host`, `Database`, `Wakeup`, `Sandbox`), and `source` for a type a host's `source` names (the
+ * repository it clones).
  */
-export const CAPABILITIES = ["host", "database", "wakeup", "source"] as const;
+export const CAPABILITIES = ["host", "database", "wakeup", "sandbox", "source"] as const;
 
 /** A resource type a connector declares with `defineResource`. */
 export const ResourceTypeEntrySchema = z.strictObject({

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";
@@ -68,6 +69,7 @@ export {
   declaredWakeup,
   defineConfig,
   envWakeup,
+  joinDeclarations,
   type Login,
   readRootSnapshot,
   resolveConfig,
@@ -78,7 +80,7 @@ export {
 // An app's `app.ts` (`defineApp`), and where the launcher finds an app's workflows and data file.
 export { type AppEntry, appSourceOf, readApps } from "./apps.ts";
 export { type AppDefinition, defineApp } from "./definitions.ts";
-export { appFolders, APPS_DIR, filesUnder, kindDirs } from "./paths.ts";
+export { appFolders, APPS_DIR, declarationFiles, filesUnder, kindDirs } from "./paths.ts";
 // `sanoma` itself (the people types' constructors) is at `@sanoma-ai/workflows/resources`, for data files.
 // `collection()` itself is at `@sanoma-ai/workflows/data`, for `resources/data.ts`; this tells one apart, as the launcher does.
 export { isCollection } from "./collection.ts";
@@ -93,6 +95,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,
@@ -175,7 +194,7 @@ export type { RunArgs } from "./run.ts";
 export { startWorker, type Worker, type WorkerOptions } from "./worker.ts";
 export { superviseWorker, type Supervisor, type SupervisorOptions } from "./supervisor.ts";
 export type { DeadlineSource, Deadlines, SelfStop, Wait } from "./deadlines.ts";
-export { nextFire, nextScheduledFire } from "./schedules.ts";
+export { nextFire, nextScheduledFire, timeMatcherFile, type TimeMatcherClass, useTimeMatcher } from "./schedules.ts";
 // `secret` itself is at `@sanoma-ai/workflows/resources`, for data files; this is the drivers' side.
 export {
   generateSecret,
@@ -234,6 +253,16 @@ export {
   databaseUrlSecret,
   storeDatabaseUrl,
 } from "./database.ts";
+export {
+  type Box,
+  type Process,
+  type SandboxBackend,
+  type SandboxCapabilities,
+  type SandboxContext,
+  type SandboxOutputs,
+  type SandboxSpec,
+} from "./sandbox-contract.ts";
+export { LOCAL_SANDBOX, localBackend } from "./local-sandbox.ts";
 export type { Chat, Chats } from "./chats.ts";
 export type { Tokens } from "./tokens.ts";
 export { type InviteRequest, openInvite, sealInvite, sealLoginCode } from "./seal.ts";
@@ -263,7 +292,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";