@sanoma-ai/workflows 0.11.5 → 0.11.9

package/src/config.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { configuredSecrets } from "./credentials.ts";
+import { inspectRun } from "./run-status.ts";
 import {
   configuredIdentityProvisioning,
   type IdentityProvisioning,
@@ -378,7 +379,11 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
       changeDriver(remotes),
       connectionDriver(connections),
       appsListDriver,
-      runtimeDriver({ tokens: tokenStore(() => connectionPool.db()), identities: identityProvisioning.store }),
+      runtimeDriver({
+        tokens: tokenStore(() => connectionPool.db()),
+        identities: identityProvisioning.store,
+        inspect: inspectRun(() => connectionPool.db(), appName),
+      }),
       ...(hostTyped ? [sourceDriver] : []),
       ...(dataStore ? [collectionsDriver(declared, dataStore)] : []),
     ],
@@ -412,6 +417,11 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
       drivers: driversByVendor,
       builtInStore: !config.secrets?.store,
       signingKeyBound: config.secrets?.bindings?.SANOMA_SIGNING_KEY !== undefined,
+      hostEnvironment: Object.fromEntries(
+        Object.entries(config.secrets?.bindings ?? {}).flatMap(([name, binding]) =>
+          binding.host && binding.env !== undefined ? [[binding.env, name]] : [],
+        ),
+      ),
       ...(isOp(config.login?.sender) && { sender: config.login.sender.vendor }),
     });
   if (types.size) {
@@ -739,6 +749,7 @@ async function readDeclared(
     drivers: ReadonlyMap<string, Driver>;
     builtInStore: boolean;
     signingKeyBound: boolean;
+    hostEnvironment: Readonly<Record<string, string>>;
     sender?: string;
   },
 ): Promise<Omit<ApplyDeclared, "rebinds">> {
@@ -760,6 +771,7 @@ async function readDeclared(
       ...(run && { secrets: run.state.secrets }),
       builtInStore: options.builtInStore,
       signingKeyBound: options.signingKeyBound,
+      hostEnvironment: options.hostEnvironment,
       ...(options.sender !== undefined && { sender: options.sender }),
       mint: !!options.mint && !!run && !run.sandbox,
     });

package/src/describe.ts

@@ -189,6 +189,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
           .map((name) => `${id}.${name}`)
           .toSorted(),
         ...(capabilities.length ? { capabilities } : {}),
+        ...(spec.host && { host: { lifetime: spec.host.capabilities.lifetime } }),
       };
     })
     .toSorted((a, b) => a.id.localeCompare(b.id));

package/src/description.ts

@@ -2,6 +2,7 @@
 // types inferred from them. zod only, no Node: a page can parse a description it is sent, and the
 // app extends `ConfigDescriptionSchema` with what it adds (`AppConfigSchema`).
 import { z } from "zod";
+import { LIFETIMES } from "./host.ts";
 import type { Outline } from "./outline.ts";
 import type { ResourceFields } from "./resource.ts";
 import { EFFECTS, FIELD_TYPES } from "./shared.ts";
@@ -322,6 +323,8 @@ export const ResourceTypeEntrySchema = z.strictObject({
   ops: z.array(z.string()),
   /** The contracts it meets (`CAPABILITIES`), in that order; absent when it meets none. */
   capabilities: z.array(z.enum(CAPABILITIES)).optional(),
+  /** For a host (`HostSpec`), how it keeps the runtime up (`HostLifetime`); absent for any other type. */
+  host: z.strictObject({ lifetime: z.enum(LIFETIMES) }).optional(),
 });
 export type ResourceTypeEntry = z.infer<typeof ResourceTypeEntrySchema>;
 

package/src/direct.ts

@@ -5,7 +5,7 @@ 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>`), 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
+ * which a page calls), run inspection, connection management, 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.
@@ -16,6 +16,7 @@ export const isDirect = (
 ): boolean =>
   op.vendor === DATA_VENDOR ||
   op.id === APPS_LIST ||
+  op.id === "sanoma.run.inspect" ||
   op.id === "sanoma.connection.disconnect" ||
   op.id === "sanoma.connection.bind" ||
   op.id === "sanoma.connection.create" ||

package/src/host-derive.ts

@@ -78,6 +78,8 @@ export interface HostFacts {
   unbound?: ReadonlyMap<string, readonly string[]>;
   /** True when the config binds `SANOMA_SIGNING_KEY`: the host is given that key, else its own (`HOST_SIGNING_KEY`). */
   signingKeyBound?: boolean;
+  /** Explicit environment delivery: destination variable to logical secret name, never values. */
+  hostEnvironment?: Readonly<Record<string, string>>;
   /**
    * While the config has no deploy-key type, the GitHub repositories a host may clone (`origin`'s,
    * a declared `source`'s) that GitHub shows to no one: private (or not there). One GitHub does
@@ -352,10 +354,17 @@ export function deriveHosts(
     ]);
     const carried = [...vendors].flatMap((vendor) => facts.carried.get(vendor) ?? []);
     for (const name of [...carried, ...facts.githubApp]) secrets[name] = secret(name);
+    for (const [environment, name] of Object.entries(facts.hostEnvironment ?? {})) {
+      if (Object.hasOwn(secrets, environment) && secrets[environment]!.$secret !== name)
+        problem(`${environment} has a derived host binding and cannot be replaced by ${name}`);
+      else if (!Object.hasOwn(secrets, environment))
+        Object.defineProperty(secrets, environment, { value: secret(name), enumerable: true });
+    }
     // One the driver reads here from the environment alone would be left off the host, and a
     // Worker updated without it would lose it.
     for (const vendor of vendors) {
       for (const name of facts.unbound?.get(vendor) ?? []) {
+        if (Object.hasOwn(facts.hostEnvironment ?? {}, name)) continue;
         problem(
           `${name} is read from the environment here, and has no binding, so the host would not be given it: bind it in sanoma.config.ts, \`secrets: { bindings: { ${name}: { env: "${name}" } } }\`, or store it on the ${vendor} connector page`,
         );
@@ -428,6 +437,7 @@ export async function hostFacts(options: {
   builtInStore: boolean;
   /** True when the config binds `SANOMA_SIGNING_KEY` (`{ env }` or `{ bootstrap }`). */
   signingKeyBound?: boolean;
+  hostEnvironment?: Readonly<Record<string, string>>;
   sender?: string;
   mint: boolean;
 }): Promise<HostFacts | undefined> {
@@ -484,6 +494,7 @@ export async function hostFacts(options: {
     carried,
     ...(unbound.size > 0 && { unbound }),
     ...(options.signingKeyBound && { signingKeyBound: true }),
+    ...(options.hostEnvironment && { hostEnvironment: options.hostEnvironment }),
     ...(options.sender !== undefined && { sender: options.sender }),
     githubApp,
     ...(sourceKey !== undefined && { sourceKey }),

package/src/host.ts

@@ -130,7 +130,8 @@ export const UNNAMED = "(the repository's name)";
 /** The port the runtime image's app listens on (its `PORT`): a host that derives runs it there. */
 export const RUNTIME_PORT = 3000;
 
-const LIFETIMES: readonly HostLifetime[] = ["long-lived", "stops-when-quiet"];
+/** Every `HostLifetime`, for a schema of one. */
+export const LIFETIMES = ["long-lived", "stops-when-quiet"] as const satisfies readonly HostLifetime[];
 
 /** 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/ledger.ts

@@ -190,6 +190,18 @@ export async function lastSignIns(
   return Object.fromEntries(last.flat());
 }
 
+/** Who minted the latest invite for `person`, and until when (ms since the epoch): from their `invite:<person>` records; undefined when none was. */
+export async function lastInvite(
+  store: LedgerStore,
+  person: string,
+): Promise<{ by: string; at: number; expiresAt: number } | undefined> {
+  const records = await store.read(`invite:${person}`);
+  const latest = records.reduce<LedgerRecord | undefined>((a, r) => (a && a.at > r.at ? a : r), undefined);
+  return latest?.type === "invite.minted"
+    ? { by: latest.by, at: latest.at, expiresAt: Date.parse(latest.expiresAt) }
+    : undefined;
+}
+
 /**
  * The `ctx.all` member a record was written in. `id` is `all:<seq>`, the run's next `seq` when
  * the `ctx.all` began, so a replay names it the same; `index` is the member's position, `size`

package/src/run-status.ts

@@ -0,0 +1,38 @@
+import type { WorkflowStatusString } from "@dbos-inc/dbos-sdk";
+import type { Db } from "./db.ts";
+
+/** Metadata only: never read a run's inputs, outputs, error or authentication data. */
+export type RunObservation = {
+  runId: string;
+  status: "missing" | "active" | "finished" | "failed" | "cancelled" | "interrupted";
+  workflow?: string;
+};
+export type InspectRun = (runId: string) => Promise<RunObservation>;
+
+const statuses: Record<WorkflowStatusString, RunObservation["status"]> = {
+  ENQUEUED: "active",
+  DELAYED: "active",
+  PENDING: "active",
+  SUCCESS: "finished",
+  ERROR: "failed",
+  MAX_RECOVERY_ATTEMPTS_EXCEEDED: "interrupted",
+  CANCELLED: "cancelled",
+};
+
+/** A snapshot of the current application's run; unknown DBOS states remain active. */
+export const inspectRun =
+  (database: () => Promise<Db>, appName: string): InspectRun =>
+  async (runId) => {
+    const db = await database();
+    const { rows } = await db.query<{ name: string; status: string }>(
+      "SELECT name,status FROM dbos.workflow_status WHERE workflow_uuid=$1 AND application_name=$2",
+      [runId, appName],
+    );
+    const row = rows[0];
+    if (!row) return { runId, status: "missing" };
+    return {
+      runId,
+      workflow: row.name,
+      status: Object.hasOwn(statuses, row.status) ? statuses[row.status as WorkflowStatusString] : "active",
+    };
+  };

package/src/runtime-ops.ts

@@ -7,6 +7,7 @@ import { sealInvite } from "./seal.ts";
 import { errorMessage } from "./shared.ts";
 import { sourceKeyPair, sshPublicKey } from "./ssh-key.ts";
 import { memoryTokens, type Tokens } from "./tokens.ts";
+import type { InspectRun } from "./run-status.ts";
 import {
   identityProvisioningCode,
   memoryIdentityProvisioning,
@@ -25,11 +26,17 @@ import {
 // registers them in every config with their driver (`runtimeDriver`), so a policy may name them;
 // a sandbox run calls `sandboxRuntimeDriver`, over its own secrets and tokens, posting nothing.
 
-/** A secret's name, as the store takes it (upper case), other than the runtime's own (`SANOMA_…`: its keys and credentials). */
-const SecretName = z
-  .string()
-  .regex(SECRET_NAME, "a secret's name: upper case, A-Z, 0-9 and _")
-  .refine((name) => !name.startsWith("SANOMA_"), "a SANOMA_ name is the runtime's own, not a workflow's to use");
+const StoredSecretName = z.string().regex(SECRET_NAME, "a secret's name: upper case, A-Z, 0-9 and _");
+/** Generation destinations exclude the runtime's keys and credentials. */
+const SecretName = StoredSecretName.refine(
+  (name) => !name.startsWith("SANOMA_"),
+  "a SANOMA_ name is the runtime's own, not a workflow's to use",
+);
+/** Database exports are stored values a lifecycle workflow can retire; bootstrap keys remain protected. */
+const DeletableSecretName = StoredSecretName.refine(
+  (name) => !name.startsWith("SANOMA_") || /^SANOMA_DATABASE_URL_[A-Z0-9_]+$/.test(name),
+  "a SANOMA_ name may be deleted only when it is an exported database URL",
+);
 
 /** How long an instance gets to answer `POST /auth/invite`. */
 const INVITE_TIMEOUT_MS = 10_000;
@@ -59,6 +66,21 @@ async function identityWrite(write: () => Promise<void>): Promise<void> {
  * `uses: [sanoma.secret.generate]` and `ctx.sanoma.secret.generate({ name, kind })`.
  */
 export const sanoma = defineConnector("sanoma", {
+  run: {
+    inspect: {
+      effect: "read",
+      idempotent: true,
+      description:
+        "Inspect a run's status in this application without its input, output or error. A snapshot, not a lock or proof that cancelled vendor calls have stopped",
+      input: z.object({ runId: z.string().min(1).max(512) }),
+      output: z.object({
+        runId: z.string(),
+        status: z.enum(["missing", "active", "finished", "failed", "cancelled", "interrupted"]),
+        workflow: z.string().optional(),
+      }),
+      target: ({ runId }: { runId: string }) => runId,
+    },
+  },
   secretStore: {
     prepare: {
       effect: "access",
@@ -127,8 +149,9 @@ export const sanoma = defineConnector("sanoma", {
     delete: {
       effect: "write",
       idempotent: true,
-      description: "Delete a stored secret; one not stored is nothing to do",
-      input: z.object({ name: SecretName }),
+      description:
+        "Delete a stored secret or exported database URL; one not stored is nothing to do. Runtime bootstrap secrets remain protected",
+      input: z.object({ name: DeletableSecretName }),
       output: z.object({}),
       target: ({ name }: { name: string }) => name,
       createsSecrets: ({ name }: { name: string }) => [name],
@@ -235,15 +258,27 @@ export async function postInvite(host: string, request: string): Promise<{ url:
 export function runtimeDriver({
   tokens,
   identities,
+  inspect,
   storage = prepareSecretStore,
   invite = postInvite,
 }: {
   tokens: Tokens;
   identities?: IdentityProvisioning;
+  inspect?: InspectRun;
   storage?: PrepareStorage;
   invite?: (host: string, request: string, call: CallContext) => Promise<{ url: string }>;
 }) {
   return defineDriver(sanoma, {
+    run: {
+      async inspect({ runId }) {
+        if (!inspect) throw refuse("run inspection is not configured");
+        try {
+          return await inspect(runId);
+        } catch {
+          throw new DriverError("Run inspection unavailable", { retryable: true });
+        }
+      },
+    },
     secretStore: {
       async prepare(input, call) {
         try {
@@ -344,6 +379,7 @@ export function runtimeDriver({
 export const sandboxRuntimeDriver = () =>
   runtimeDriver({
     tokens: memoryTokens(),
+    inspect: async (runId) => ({ runId, status: "missing" }),
     identities: memoryIdentityProvisioning(),
     storage: memoryStorageProvisioning(),
     invite: async (host, _request, call) => ({ url: new URL(`/auth/invite/sandbox-${tokenIdOf(call)}`, host).href }),

package/src/secret-store.ts

@@ -79,9 +79,16 @@ export const isSecretStoreFactory = (store: SecretStore | SecretStoreFactory): s
   "kind" in store && store.kind === "runtime";
 
 export type SecretBinding =
-  | { path: string; management: "sanoma" | "external"; env?: never; bootstrap?: never }
-  | { env: string; management?: "external"; path?: never; bootstrap?: never }
-  | { bootstrap: DeploymentKeyName; management?: "external"; env?: never; path?: never };
+  | { path: string; management: "sanoma" | "external"; env?: never; bootstrap?: never; host?: never }
+  | {
+      env: string;
+      /** Deliver this binding to declared deriving hosts under its environment name. */
+      host?: boolean;
+      management?: "external";
+      path?: never;
+      bootstrap?: never;
+    }
+  | { bootstrap: DeploymentKeyName; management?: "external"; env?: never; path?: never; host?: never };
 
 export interface SecretConfiguration {
   /** Omitted: built-in encrypted Postgres, supplied by the runtime. */
@@ -161,8 +168,10 @@ export function checkSecretConfiguration(config: SecretConfiguration): void {
     (!config.bindings || typeof config.bindings !== "object" || Array.isArray(config.bindings))
   )
     invalid();
+  const hostEnvironment = new Set<string>();
   for (const [name, b] of Object.entries(config.bindings ?? {})) {
     if (!namePattern.test(name) || !b || typeof b !== "object") invalid();
+    if (b.host !== undefined && (typeof b.env !== "string" || typeof b.host !== "boolean")) invalid();
     if (DEPLOYMENT_KEYS.includes(name) && !("env" in b) && !("bootstrap" in b)) invalid();
     if ("bootstrap" in b) {
       if (
@@ -180,6 +189,10 @@ export function checkSecretConfiguration(config: SecretConfiguration): void {
         (b.management !== undefined && b.management !== "external")
       )
         invalid();
+      if (b.host) {
+        if (hostEnvironment.has(b.env!)) invalid();
+        hostEnvironment.add(b.env!);
+      }
     } else if (!nonempty(b.path) || !["sanoma", "external"].includes(b.management)) invalid();
   }
 }

package/src/shared.ts

@@ -387,6 +387,9 @@ export function refusalOf(
 /** A declared resource as the people functions read it: only the runtime's people types count. */
 export type PeopleResource = Pick<DeclaredResource, "vendor" | "type" | "desired">;
 
+/** The group the runtime holds a change to the rules for, and the one that hands out invite links. */
+export const ADMIN = "admin";
+
 /** The group every agent is in, the runtime's own among them: no data file declares it. */
 export const AGENTS = "agents";
 

package/src/source.ts

@@ -322,6 +322,8 @@ export interface RemoteHalf {
   webhook?(request: Request, context: RemoteContext): Promise<RemoteEvent[]>;
   /** The accounts the company's app on the host is installed on: where it acts with no person's token. */
   owners?(context: RemoteContext): Promise<{ login: string; kind: "user" | "organization" }[]>;
+  /** The permissions the company's app on the host holds, by name (`contents: "write"`), as the host lists them; undefined without the app's keys. */
+  permissions?(context: RemoteContext): Promise<Record<string, string> | undefined>;
 }
 
 /** The remote half among `remotes` (`ResolvedConfig.remotes`) whose host `url` is on, with its vendor and the repository. */