@sanoma-ai/workflows 0.7.0 → 0.8.0

package/src/demo.ts

@@ -2,9 +2,9 @@ import type { SanomaClient } from "./client.ts";
 import type { ResolvedConfig } from "./config.ts";
 import { DATA_TABLE } from "./db.ts";
 import { applyGivens } from "./sandbox.ts";
-import { loadScenarios, type Moment } from "./scenario.ts";
+import { type Given, loadScenarios, type Moment } from "./scenario.ts";
 import { memorySecrets } from "./secret.ts";
-import { errorMessage } from "./shared.ts";
+import { DATA_VENDOR, errorMessage } from "./shared.ts";
 
 /*
  * A demo: a company repo run on its connectors' fakes, with the world its scenarios describe.
@@ -27,20 +27,43 @@ export interface DemoState {
 const states = new WeakMap<ResolvedConfig, DemoState>();
 
 /**
- * Seeds the demo instance afresh: empties the collections' table, resets the instance's fakes,
+ * A half of a demo's seed (`reseed`'s `only`): what goes into its `database` (the runs cancelled,
+ * `sanoma_data` emptied, the worlds' collection records, the moments' runs), or into its `memory`
+ * (the instance's fakes reset, the worlds' vendor objects and calls). A copy of a seeded database
+ * holds the first half but not the second, which a process over it applies to its own fakes.
+ */
+export type SeedHalf = "database" | "memory";
+
+/** Which half a world's `Given` goes to: a collection's operation the database, anything else memory; a fault both, each refusing it. */
+const halfOf = (g: Given, resolved: ResolvedConfig): SeedHalf | undefined =>
+  "fault" in g ? undefined : "op" in g && resolved.ops.get(g.op)?.vendor === DATA_VENDOR ? "database" : "memory";
+
+/**
+ * Seeds the demo instance afresh: cancels the app's unfinished runs (`cancelUnfinished`: the last
+ * seed's moments among them), empties the collections' table, resets the instance's fakes,
  * applies every world (a scenario with no `When`) to the instance (`applyGivens`: its records
  * saved through the collections' driver, its vendor objects put in the fakes), then starts each
  * moment as a sandbox run by its person, left undriven, so its first approval waits for them.
- * `resolved` is the resolution the worker and `client` run on, made with `fakes: "instance"`.
- * A world or a moment that fails is a problem in the state it returns, and the rest go on.
+ * `only` seeds one half (`SeedHalf`). `resolved` is the resolution the worker and `client` run
+ * on, made with `fakes: "instance"`. A world or a moment that fails is a problem in the state it
+ * returns, and the rest go on.
  */
-export async function reseed(client: SanomaClient, resolved: ResolvedConfig): Promise<DemoState> {
+export async function reseed(
+  client: SanomaClient,
+  resolved: ResolvedConfig,
+  { only }: { only?: SeedHalf } = {},
+): Promise<DemoState> {
   const fakes = resolved.instanceFakes;
   if (!fakes) throw new Error('reseed seeds an instance on fakes: resolve its config with `fakes: "instance"`');
+  const into = (half: SeedHalf) => only === undefined || only === half;
   // Read first, so scenarios that cannot be read at all leave the instance as it was.
   const { scenarios, errors } = await loadScenarios(resolved);
-  if (resolved.dataStore) await (await resolved.dataStore.db()).query(`TRUNCATE ${DATA_TABLE}`);
-  for (const fake of fakes.values()) fake.reset();
+  if (into("database")) {
+    // The last seed's moments, and whatever a visitor started since, end here: nothing is kept.
+    await client.cancelUnfinished();
+    if (resolved.dataStore) await (await resolved.dataStore.db()).query(`TRUNCATE ${DATA_TABLE}`);
+  }
+  if (into("memory")) for (const fake of fakes.values()) fake.reset();
   const state: DemoState = {
     seededAt: new Date().toISOString(),
     worlds: [],
@@ -49,28 +72,36 @@ export async function reseed(client: SanomaClient, resolved: ResolvedConfig): Pr
   };
   const secrets = memorySecrets();
   for (const world of scenarios.filter((s) => s.workflow === undefined)) {
+    // Each Given keeps its place in the world, so its call's idempotency key is the same in either half.
+    const kept = [...world.given.entries()].filter(([, g]) => {
+      const half = halfOf(g, resolved);
+      return half === undefined || into(half);
+    });
     try {
-      await applyGivens(world, {
-        kind: "instance",
-        drivers: resolved.drivers,
-        fakes,
-        ops: resolved.ops,
-        call: (i, opId) => ({
-          idempotencyKey: `world:${world.name}:${i}`,
-          runId: `world:${world.name}`,
-          opId,
-          attempt: 1,
-          secrets,
-          // Who its records are by: whoever it says is acting, else the runtime's own agent.
-          by: world.startedBy ?? "scenarios",
-        }),
-      });
+      await applyGivens(
+        { name: world.name, given: kept.map(([, g]) => g) },
+        {
+          kind: "instance",
+          drivers: resolved.drivers,
+          fakes,
+          ops: resolved.ops,
+          call: (i, opId) => ({
+            idempotencyKey: `world:${world.name}:${kept[i]![0]}`,
+            runId: `world:${world.name}`,
+            opId,
+            attempt: 1,
+            secrets,
+            // Who its records are by: whoever it says is acting, else the runtime's own agent.
+            by: world.startedBy ?? "scenarios",
+          }),
+        },
+      );
       state.worlds.push(world.name);
     } catch (err) {
       state.problems.push(`world "${world.name}": ${errorMessage(err)}`);
     }
   }
-  for (const s of scenarios) {
+  for (const s of into("database") ? scenarios : []) {
     if (!s.moment || s.workflow === undefined) continue;
     try {
       const runId = await client.start(s.workflow, s.input, { sandbox: s.name, startedBy: s.moment.person });

package/src/describe.ts

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import type { z } from "zod";
+import { type AppEntry, appsAt } from "./apps.ts";
 import { type LintProblem, readSource, type SourceFile } from "./ast.ts";
 import { type Field, recordSchemaOf } from "./collection.ts";
 import { connectorsOf, resolveConfig, rootOf, type SanomaConfig } from "./config.ts";
@@ -14,6 +15,7 @@ import {
   type DataFiles,
   type DeclaredCollection,
   type DeclaredResource,
+  inAppPeople,
   readDataFiles,
   type ResourceProblem,
 } from "./resources.ts";
@@ -62,8 +64,19 @@ export {
   type Bindings,
   type Rebind,
 } from "./lockfile.ts";
+// The apps under `apps/`, read without running their `app.ts`.
+export { crossAppImports, readApps, type AppEntry } from "./apps.ts";
 // What the sites call, read from their source: a workflow's Used by.
-export { readSites, type SiteCall, type SiteEntry, type SitePage, siteContentPages, siteLocales } from "./sites.ts";
+export {
+  readSites,
+  type SiteCall,
+  type SiteEntry,
+  type SitePage,
+  siteContentPages,
+  siteIcons,
+  siteLocales,
+  sitesUnder,
+} from "./sites.ts";
 // The generated SDK, `.sanoma/api.ts`: a site's `api` typed from this description.
 export { API_FILE, generateApi, writeApi, writeGenerated } from "./sdk.ts";
 // The Cedar schema, `.sanoma/schema.cedarschema`: what a company's policies are validated and decided against.
@@ -76,7 +89,10 @@ export type { ApplyInput, ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanS
 
 /** What a workflow is, read from its definition: enough to draw a start form and show what it may call. */
 export interface WorkflowEntry {
+  /** Its name: `<app>.<name>` for one an app's folder defines. */
   name: string;
+  /** The app whose folder defines it (`apps/<app>/workflows/`); absent for one at the root. */
+  app?: string;
   title?: string;
   /** `manual`, or the schedule it starts on (`defineWorkflow`'s `trigger`). */
   trigger: Trigger;
@@ -166,7 +182,10 @@ export interface ResourceTypeEntry {
 
 /** A collection the config declares (`collection()`). */
 export interface CollectionEntry {
+  /** Its name: `<app>.<name>` for one an app's `resources/data.ts` declares. */
   name: string;
+  /** The app whose folder declares it (`apps/<app>/resources/data.ts`); absent for one at the root. */
+  app?: string;
   title?: string;
   /** The field each record is found by. */
   key: string;
@@ -204,8 +223,14 @@ export interface ConfigDescription {
   resources: DeclaredResource[];
   /** Each binding in the lockfile (`LOCKFILE`) whose key no data file declares, as `readDataFiles` reports it. */
   orphans: DataFiles["orphans"];
-  /** What is wrong in the data files (`readDataFiles`), each at its file, relative to the root, line and column. A workflow's are on its entry. */
+  /**
+   * What is wrong in the data files (`readDataFiles`) and the apps (a folder of `apps/` that is no
+   * app, an `app.ts` that cannot be read, a collection or site at the root named as an app is),
+   * each at its file, relative to the root, line and column. A workflow's are on its entry.
+   */
   problems: ResourceProblem[];
+  /** The apps under `apps/` (`readApps`), by name. Each workflow, collection and site an app declares names it (`app`). */
+  apps: AppEntry[];
   /**
    * `defined` when the root has `policies/**\/*.cedar` (else the policy is `allowAll`), with their
    * `version`, or while they have `problems` (`policyProblems`), none: then every call and start is refused.
@@ -258,6 +283,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
   const collections: CollectionEntry[] = [...resolved.collections.values()]
     .map((c) => ({
       name: c.name,
+      ...(c.app !== undefined && { app: c.app }),
       ...(c.title !== undefined && { title: c.title }),
       key: c.key,
       fields: c.fields,
@@ -294,6 +320,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
         ];
     return {
       name: wf.name,
+      ...(wf.app !== undefined && { app: wf.app }),
       title: wf.title,
       trigger: wf.trigger,
       ...(builtin && { builtin: true as const }),
@@ -308,6 +335,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
   });
   workflows.sort((a, b) => a.name.localeCompare(b.name));
   addApiNameProblems(workflows, new Set(ops.map((op) => op.vendor)));
+  const { apps, problems: appProblems } = appsAt(resolved.root);
   const sites = readSites(
     resolved.root,
     { workflows, collections, ops },
@@ -323,9 +351,16 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
     vendors,
     resourceTypes,
     collections,
-    resources: dataFiles.resources,
+    // An app's people are refused (`readPeople`), so the grid and the People page never show them.
+    resources: dataFiles.resources.filter((r) => !inAppPeople(r)),
     orphans: dataFiles.orphans,
-    problems: [...dataFiles.problems, ...domainProblems(resolved.root, dataFiles.resources, resources, sites, read)],
+    problems: [
+      ...dataFiles.problems,
+      ...appProblems,
+      ...appClashes(apps, collections, sites),
+      ...domainProblems(resolved.root, dataFiles.resources, resources, sites, read),
+    ],
+    apps,
     policy: {
       defined: resolved.policy !== allowAll,
       ...(resolved.policy.version === undefined ? {} : { version: resolved.policy.version }),
@@ -335,6 +370,34 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
   };
 }
 
+/** That the root's `kind` `name`, in `file`, is named as an app is. */
+const appClash = (kind: string, name: string, file: string): ResourceProblem => ({
+  file,
+  line: 1,
+  column: 1,
+  message: `the ${kind} ${name} is named as the app apps/${name} is: name it otherwise`,
+});
+
+/**
+ * A collection or site at the root named as an app is: `api.data.<app>` and `/sites/<app>/` are
+ * the app's, so the root's would take its place.
+ */
+function appClashes(
+  apps: readonly AppEntry[],
+  collections: readonly CollectionEntry[],
+  sites: readonly SiteEntry[],
+): ResourceProblem[] {
+  const names = new Set(apps.map((app) => app.name));
+  return [
+    ...collections
+      .filter((c) => c.app === undefined && names.has(c.name))
+      .map((c) => appClash("collection", c.name, c.declared?.file ?? "resources/data.ts")),
+    ...sites
+      .filter((site) => site.app === undefined && names.has(site.name))
+      .map((site) => appClash("site", site.name, `sites/${site.name}`)),
+  ];
+}
+
 /**
  * Each site a host's `domains` (its type's `host.inputs.domains`) names that is not a public
  * site, and each domain it gives more than one site, at the host's declaration: the app serves

package/src/direct.ts

@@ -1,15 +1,19 @@
 import type { Op } from "./op.ts";
 import { isResourceOp } from "./resource.ts";
-import { DATA_VENDOR } from "./shared.ts";
+import { APPS_LIST, DATA_VENDOR } from "./shared.ts";
 
 /**
  * Whether an operation may be called directly, outside a run (`SanomaClient.call`), as the
- * person: a collection's (`data.<name>.<op>`), or a `read` that is neither the runtime's own
- * (the vendor `sanoma`) nor a resource type's (`isResourceOp`), which only drift and apply call.
+ * person: a collection's (`data.<name>.<op>`), the runtime's listing of apps (`sanoma.apps.list`,
+ * which a page calls), or a `read` that is neither the runtime's own (the vendor `sanoma`) nor a
+ * resource type's (`isResourceOp`), which only drift and apply call.
  * Anything else (an effect at a vendor) is a workflow's. The one rule: the built-in `call`
  * workflow, the SDK and the app read it, from here or from `OpEntry.direct`, and never derive it.
  */
 export const isDirect = (
-  op: Pick<Op, "vendor" | "resource" | "effect">,
+  op: Pick<Op, "id" | "vendor" | "resource" | "effect">,
   types: ReadonlyMap<string, unknown>,
-): boolean => op.vendor === DATA_VENDOR || (op.effect === "read" && op.vendor !== "sanoma" && !isResourceOp(op, types));
+): boolean =>
+  op.vendor === DATA_VENDOR ||
+  op.id === APPS_LIST ||
+  (op.effect === "read" && op.vendor !== "sanoma" && !isResourceOp(op, types));

package/src/errors.ts

@@ -51,6 +51,9 @@ export function errorCode(e: unknown): ErrorCode | undefined {
   return code !== undefined && KNOWN.has(code) ? (code as ErrorCode) : undefined;
 }
 
+/** A `DriverError`'s `vendorCode` (`no_token`, `bad_signature`), read as a property: undefined for anything else. */
+export const vendorCodeOf = (e: unknown): string | undefined => own<string>(e, "vendorCode", "string");
+
 /**
  * True when the error says trying again would only repeat it (`retryable: false`), as a
  * `DriverError` for a vendor's final answer or a ledger store for a corrupt file does. Read as

package/src/fake.ts

@@ -9,6 +9,9 @@ import {
   type Specs,
   withSetup,
 } from "./op.ts";
+import { fail, type Instance, UNREGISTERED, type WakeupApi, wakeupCalls } from "./wakeup-driver.ts";
+import { INSTANCE_TOKEN, instanceUrl } from "./wakeup-service.ts";
+import { wakeupOps } from "./wakeup-type.ts";
 
 /*
  * Fake vendors for tests, at `@sanoma-ai/workflows/fake`. Kept off the main entry so the
@@ -166,3 +169,137 @@ export function defineFake<V extends string, S extends Specs, T extends Record<s
 export function withFake<C extends Connector<any, any>>(connector: C, fake: Fake<any, any>): C {
   return withSetup(connector, { driver: () => fake.driver, fake: () => fake });
 }
+
+// The built-in `sanoma.wakeup`'s fake: an in-memory wakeup service that calls the host's `/wake`.
+
+/** An instance of the fake wakeup service, as it keeps one. */
+interface FakeInstance extends Instance {
+  token: string;
+}
+
+interface FakeWakeupState extends Record<string, unknown> {
+  seq: number;
+  instances: Record<string, FakeInstance>;
+}
+
+/** How long the fake waits before it sends a wake again that the host did not answer. */
+const RETRY_MS = 250;
+/** setTimeout's longest delay: a longer one fires at once. */
+const MAX_DELAY_MS = 2 ** 31 - 1;
+
+/** The URL as the service keeps it (`instanceUrl`, its own rule), or the service's 400. */
+function checkedUrl(value: string): string {
+  const checked = instanceUrl(value);
+  if ("error" in checked) throw fail(checked.error, 400);
+  return checked.url;
+}
+
+/**
+ * An in-memory wakeup service for tests, as `sanoma wakeup` answers: instances in
+ * `state.instances`, ids made in order (UUID-shaped), each named by the token it was posted with
+ * (the call's `SANOMA_WAKEUP_TOKEN`), so posting it again moves it. `register` takes only the
+ * instance's own token and replaces the wake it had; it then sends `GET {host}/wake` at `at`,
+ * again every 250 ms until the host answers 2xx. `fire()` sends every armed wake now; `close()`
+ * (and `reset()`) disarms them.
+ */
+export function fakeSanomaWakeup(options: FakeOptions = {}) {
+  /** The wake each instance waits to send, by its id. */
+  const armed = new Map<string, { at: number; url: string; timeout?: NodeJS.Timeout; sending?: boolean }>();
+  const disarm = (id: string) => {
+    clearTimeout(armed.get(id)?.timeout);
+    armed.delete(id);
+  };
+  /** Sends `id`'s armed wake once it is due, while it is still the one armed, until the host answers. */
+  const send = async (id: string, pending = armed.get(id)) => {
+    // One request at a time: the one in flight sends again if it is not answered.
+    if (!pending || armed.get(id) !== pending || pending.sending) return;
+    const due = pending.at - Date.now();
+    if (due > 0) {
+      pending.timeout = setTimeout(() => void send(id, pending), Math.min(due, MAX_DELAY_MS)).unref();
+      return;
+    }
+    pending.sending = true;
+    const answered = await fetch(`${pending.url}/wake`).then(
+      (res) => res.ok,
+      () => false,
+    );
+    pending.sending = false;
+    if (armed.get(id) !== pending) return;
+    if (answered) armed.delete(id);
+    else pending.timeout = setTimeout(() => void send(id, pending), RETRY_MS).unref();
+  };
+
+  const api = (state: FakeWakeupState): WakeupApi => ({
+    async put(url, token) {
+      const checked = checkedUrl(url);
+      if (!INSTANCE_TOKEN.test(token)) throw fail("token must be an instance's token", 400);
+      const mine = Object.values(state.instances).find((i) => i.token === token);
+      if (mine) {
+        // The same instance, moved: its wake there forgotten.
+        if (mine.url !== checked) {
+          Object.assign(mine, { url: checked, ...UNREGISTERED });
+          disarm(mine.id);
+        }
+        return { id: mine.id };
+      }
+      const id = `00000000-0000-4000-8000-${String(++state.seq).padStart(12, "0")}`;
+      state.instances[id] = { id, url: checked, ...UNREGISTERED, token };
+      return { id };
+    },
+    async get(id) {
+      const found = state.instances[id];
+      if (!found) return undefined;
+      const { token: _, ...shown } = found;
+      return shown;
+    },
+    async remove(id) {
+      delete state.instances[id];
+      disarm(id);
+    },
+    async wake({ at }, token) {
+      // The token names the instance.
+      const mine = Object.values(state.instances).find((i) => i.token === token);
+      if (!mine) throw fail("the token is no instance's", 401);
+      Object.assign(mine, { at: new Date(at).toISOString(), lastError: null });
+      disarm(mine.id);
+      armed.set(mine.id, { at: Date.parse(at), url: mine.url });
+      void send(mine.id);
+    },
+  });
+
+  const fake = defineFake(
+    wakeupOps,
+    {
+      initial: (): FakeWakeupState => ({ seq: 0, instances: {} }),
+      ops: (state) => ({ wakeup: wakeupCalls(() => api(state)) }),
+    },
+    options,
+  );
+  const close = () => {
+    for (const id of armed.keys()) disarm(id);
+  };
+  const { reset } = fake;
+  return Object.assign(fake, {
+    /** Sends every armed wake now, whatever its `at`; resolves once the hosts answered them, or fails after 60 s. */
+    async fire() {
+      const fired = [...armed].map(([id, pending]) => {
+        clearTimeout(pending.timeout);
+        pending.at = 0;
+        void send(id, pending);
+        return pending;
+      });
+      const until = Date.now() + 60_000;
+      while (fired.some((p) => [...armed.values()].includes(p))) {
+        if (Date.now() > until) throw new Error("sanoma.wakeup fake: a fired wake was not answered in 60 s");
+        await new Promise((r) => setTimeout(r, 50));
+      }
+    },
+    /** Disarms every armed wake. */
+    close,
+    /** Empties the state and disarms every armed wake. */
+    reset() {
+      close();
+      reset();
+    },
+  });
+}

package/src/host.ts

@@ -7,14 +7,13 @@ import type { z } from "zod";
 /**
  * How a host keeps the runtime up:
  * - `long-lived`: the process is restarted if it exits, and never stopped for being quiet (Docker).
- * - `stops-on-exit`: the host stops the instance when its process exits, and starts it again on
- *   the next request (Fly).
  * - `stops-when-quiet`: the host stops the instance after a while without inbound requests, and
  *   starts it again on the next request (a free Render service, Cloudflare Containers).
  *
  * A host that stops needs a declared `Wakeup` for what is due at a time while it is stopped.
+ * Later: `stops-on-exit`, with a host that stops the instance when its process exits (Fly).
  */
-export type HostLifetime = "long-lived" | "stops-on-exit" | "stops-when-quiet";
+export type HostLifetime = "long-lived" | "stops-when-quiet";
 
 /** What a host can do, for choosing one. */
 export interface HostCapabilities {
@@ -62,7 +61,7 @@ export interface HostSpec {
   outputs: (state: Record<string, unknown>) => HostOutputs;
 }
 
-const LIFETIMES: readonly HostLifetime[] = ["long-lived", "stops-on-exit", "stops-when-quiet"];
+const LIFETIMES: readonly HostLifetime[] = ["long-lived", "stops-when-quiet"];
 
 /** True when `schema` has a field at the dotted `path`, looking through optional, nullable and default wrappers. */
 export function hasPath(schema: z.ZodType, path: string): boolean {

package/src/index.ts

@@ -61,6 +61,9 @@ export {
   type ResolvedConfig,
   type SanomaConfig,
 } from "./config.ts";
+// An app's `app.ts` (`defineApp`), and where the launcher finds an app's workflows and data file.
+export { type AppDefinition, type AppEntry, defineApp, readApps } from "./apps.ts";
+export { appFolders, APPS_DIR, 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";
@@ -76,12 +79,15 @@ export {
 } from "./apply.ts";
 export { CALL_WORKFLOW, CallInput } from "./call-workflow.ts";
 export {
+  type ChangeDecision,
+  type ChangeDeploy,
   type ChangeEvent,
   ChangeFacts,
   ChangeInput,
   changeOps,
   type ChangeReport,
   type ChangeState,
+  type ChangeVerified,
   runtimeHold,
   touchesOf,
 } from "./change.ts";
@@ -125,6 +131,7 @@ export {
   ApprovalPendingError,
   errorCode,
   type ErrorCode,
+  vendorCodeOf,
   type ErrorInfo,
   type InputIssue,
   invalidInput,
@@ -149,8 +156,6 @@ 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";
-// Whether a wake is the one the instance's worker last registered, for the `/wake` route.
-export { shouldWake } from "./db.ts";
 export { nextFire, nextScheduledFire } from "./schedules.ts";
 // `secret` itself is at `@sanoma-ai/workflows/resources`, for data files; this is the drivers' side.
 export {
@@ -163,12 +168,23 @@ export {
   type Secrets,
 } from "./secret.ts";
 export {
+  type AppMerge,
   type CheckResult,
   type Draft,
+  draftBranch,
   type DraftDiff,
+  draftOf,
+  type HostEnforcement,
+  type PullRequest,
+  type RemoteContext,
+  type RemoteEvent,
+  type RemoteHalf,
+  remoteFor,
+  type RepoRef,
   resolveRevision,
   SOURCE_RESOLVE,
   type Source,
+  type SourceHost,
 } from "./source.ts";
 export type { HostCapabilities, HostLifetime, HostOutputs, HostSpec } from "./host.ts";
 export {
@@ -186,11 +202,12 @@ export {
   type WakeupOutputs,
   type WakeupRegistration,
   type WakeupSpec,
-  wakeGeneration,
   wakeupHostTypes,
 } from "./wakeup.ts";
 export {
   type CallOptions,
+  type ChangesFilter,
+  type ChangeView,
   type ClientOptions,
   SanomaClient,
   type RunsFilter,
@@ -212,12 +229,14 @@ export {
   CHANGE_MERGE,
   CHANGE_OPEN,
   CHANGE_REVIEW,
+  CHANGE_TOPIC,
   CHANGE_WORKFLOW,
   declaresPeople,
   type PeopleResource,
   personOf,
   principalOf,
   RUNTIME_AGENTS,
+  HOST_CHECK_AGENT,
   SCHEDULE_AGENT,
   credentialReady,
   DEFAULT_SLEEP_NAME,

package/src/lint.ts

@@ -1,9 +1,9 @@
 import { realpathSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, relative, sep } from "node:path";
 import { byPosition, childrenOf, type LintProblem, type Node, parsed, type SourceFile } from "./ast.ts";
 import { COLLECTIONS_FILE, readDataFile } from "./datafile.ts";
 import { constsOf, outlineBody, workflowLiterals } from "./outline.ts";
-import { inside, nearestDir, RELATIVE } from "./paths.ts";
+import { APPS_DIR, inside, nearestDir, RELATIVE } from "./paths.ts";
 // From src/ and from dist/ alike, the package's own oxlint.json: the one list of allowed names.
 import oxlint from "../oxlint.json" with { type: "json" };
 
@@ -29,7 +29,7 @@ const ALLOWED_PACKAGE = new RegExp(`^(${[...AUTHOR_PACKAGES, "@sanoma-ai/connect
 const REFUSED_PACKAGES: [RegExp, string][] = [
   [/^@sanoma-ai\/testing(\/|$)/, `fakes and test helpers belong in tests; ${THROUGH_CTX}`],
   [/^@sanoma-ai\/app(\/|$)/, "the app starts runs and decides approvals, so a workflow could approve itself"],
-  [/^@sanoma-ai\/connector-[^/]+\/(fake|driver)(\/|$)/, `${THROUGH_CTX}; import the connector itself`],
+  [/^@sanoma-ai\/connector-[^/]+\/(fake|driver|remote)(\/|$)/, `${THROUGH_CTX}; import the connector itself`],
   [/^sanoma\//, "`sanoma` has no entry points for a workflow: import its names from `sanoma` itself"],
 ];
 
@@ -203,11 +203,14 @@ function whyRefused(spec: string, filename: string | undefined, root: string | u
     const target = join(dirname(filename), spec);
     if (inside(root, target)) return undefined;
     const tree = basename(root) === "workflows";
-    // The collections, which a workflow names in `uses`: the one data file the runtime imports too.
-    if (tree && realPath(target) === realPath(join(dirname(root), "resources", COLLECTIONS_FILE))) return undefined;
+    // The collections, which a workflow names in `uses`: the one data file the runtime imports too,
+    // the root's or an app's (`apps/<app>/resources/data.ts`), wherever the workflow is.
+    if (tree && isCollectionsFile(realPath(target), realPath(dirname(root)))) return undefined;
     return (
       `it reaches outside ${tree ? `${basename(root)}/` : "this directory"}, toward the config and its drivers; ${THROUGH_CTX}` +
-      (tree ? "; of the files outside it, only resources/data.ts (the collections) may be imported" : "")
+      (tree
+        ? "; of the files outside it, only resources/data.ts (the collections, the root's or an app's apps/<app>/resources/data.ts) may be imported"
+        : "")
     );
   }
   for (const [pattern, reason] of REFUSED_PACKAGES) if (pattern.test(spec)) return reason;
@@ -215,6 +218,18 @@ function whyRefused(spec: string, filename: string | undefined, root: string | u
   return "import only from `sanoma` (or `@sanoma-ai/workflows`), a `@sanoma-ai/connector-*` package, zod, or a file beside this one";
 }
 
+/**
+ * Whether `target` is a collections file of the company whose workflows' tree is in `base` (the
+ * root, or an app's `apps/<app>/`): `<root>/resources/data.ts` or `<root>/apps/<app>/resources/data.ts`.
+ */
+function isCollectionsFile(target: string, base: string): boolean {
+  const root = basename(dirname(base)) === APPS_DIR ? dirname(dirname(base)) : base;
+  const parts = relative(root, target).split(sep);
+  const [first, app] = parts;
+  const rest = first === APPS_DIR && app !== undefined ? parts.slice(2) : parts;
+  return rest.length === 2 && rest[0] === "resources" && rest[1] === COLLECTIONS_FILE;
+}
+
 /** A path's real path, or the path itself when it does not exist. */
 function realPath(path: string): string {
   try {

package/src/op.ts

@@ -2,6 +2,7 @@ import type { ProviderV4 } from "@ai-sdk/provider";
 import type { z } from "zod";
 import type { Fake } from "./fake.ts";
 import type { Secrets } from "./secret.ts";
+import type { RemoteHalf } from "./source.ts";
 import type { Steps } from "./steps.ts";
 
 /**
@@ -308,7 +309,8 @@ export interface Driver {
  * to call: the config then names the connector alone, and never a driver, a fake, steps or a
  * login. Any may be missing: a workflow using an operation of a connector with no driver is
  * refused, a connector with no fake has none for sandbox runs, one with no login half signs no
- * visitor in, and one with no model half gives the app no models.
+ * visitor in, one with no model half gives the app no models, and one with no remote half hosts
+ * no repository a change is reviewed on.
  */
 export interface ConnectorSetup {
   /** Makes the live driver, which reads its credentials from the environment when called: once per resolved config. */
@@ -331,6 +333,11 @@ export interface ConnectorSetup {
    * and a missing one fails that call.
    */
   model?: (context: ModelContext) => ProviderV4 | Promise<ProviderV4>;
+  /**
+   * Makes the connector's remote half, a git host's pull requests, statuses and webhooks: once per
+   * resolved config (`ResolvedConfig.remotes`). It reads its credentials when called.
+   */
+  remote?: () => RemoteHalf;
 }
 
 /** What the app gives a connector's model half (`ConnectorSetup.model`): the secrets, as a login half reads them. */