@sanoma-ai/workflows 0.1.0 → 0.4.0

package/dist/client.js

@@ -3,15 +3,29 @@ import { isDeepStrictEqual } from "node:util";
 import { Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
 import { z } from "zod";
 import { APPROVALS_EVENT, ApprovalMessage, decisionEventOf, messageKeyOf, topicOf } from "./approvals.js";
+import { beforeOf, decideCall, decideStart, recorded, startHoldOf } from "./call.js";
+import { collectionsDriver } from "./collection.js";
 import { resolveConfig } from "./config.js";
-import { deleteCredential, storeCredential, storedCredentials } from "./credentials.js";
+import { deleteCredential, storeCredential, storedCredentials, storedSecrets } from "./credentials.js";
 import { dbosClient, lazyPool } from "./db.js";
 import { credentialsOf } from "./env.js";
-import { notApprover, Principal } from "./define.js";
+import { Principal } from "./define.js";
+import { APPLY_WORKFLOW } from "./apply.js";
 import { DRIFT_WORKFLOW } from "./drift.js";
-import { parseOrThrow, SanomaError } from "./errors.js";
-import { ownedLedger } from "./ledger.js";
-import { isEnded, mayDecide } from "./shared.js";
+import { isDirect } from "./direct.js";
+import { ApprovalPendingError, errorCode, errorInfo, parseOrThrow, PolicyDeniedError, SanomaError, } from "./errors.js";
+import { insertRecord, ownedLedger } from "./ledger.js";
+import { allowAll } from "./policy.js";
+import { admit, readPeople } from "./resources.js";
+import { BUILT_IN_WORKFLOWS, CALL_WORKFLOW, DATA_VENDOR, errorMessage, isEnded, refusalOf, WORKFLOW_ACTION, } from "./shared.js";
+/** A principal, or its id alone. */
+const PrincipalOrId = z.union([
+    z
+        .string()
+        .regex(/\S/)
+        .transform((id) => ({ id })),
+    Principal,
+]);
 /**
  * The run status each DBOS status maps to. `waiting` is PENDING with an approval pending, so
  * only the approvals tell it from `running`. Keyed by every DBOS status, so one a later DBOS
@@ -56,12 +70,15 @@ export class SanomaClient {
     audit;
     /** On the config's database, for the credentials table: opened on first use. */
     credentialsPool;
+    /** What a direct call's driver reads secrets from, as a worker's live driver does. */
+    storedSecrets;
     constructor(dbos, config, drivers) {
         this.dbos = dbos;
         this.config = config;
         this.drivers = drivers;
         this.audit = ownedLedger(config);
         this.credentialsPool = lazyPool(config.databaseUrl, "credentials");
+        this.storedSecrets = storedSecrets(() => this.credentialsDb(), "sanoma");
     }
     /**
      * Connects to the runtime's Postgres for the config's app. Checks the config first and throws
@@ -80,6 +97,7 @@ export class SanomaClient {
      * `workflow` is a definition, or the name of one in the config's `workflows`.
      */
     async start(workflow, input, options) {
+        const startedBy = await this.admitted(parseOrThrow(PrincipalOrId, options?.startedBy, '`startedBy` must be a principal, such as "alice" or { id: "alice" }'));
         if (typeof workflow === "string") {
             const named = this.config.workflows.get(workflow);
             if (!named) {
@@ -91,11 +109,13 @@ export class SanomaClient {
             }
             workflow = named;
         }
-        parseOrThrow(workflow.input, input, `The input does not match ${workflow.name}'s schema`);
-        const startedBy = parseOrThrow(Principal, options?.startedBy, '`startedBy` must be a principal, such as { id: "alice" }');
+        // The policy decides the start on the input as parsed, its defaults filled, as the Cedar schema types it.
+        const parsed = parseOrThrow(workflow.input, input, `The input does not match ${workflow.name}'s schema`);
         const { runId } = options;
         const sandbox = parseOrThrow(z.string().min(1).optional(), options.sandbox, "`sandbox` must be the name of a scenario in the config's `scenarios/`");
-        const args = { input, startedBy, ...(sandbox === undefined ? {} : { sandbox }) };
+        const hold = await this.startHold(workflow.name, parsed, startedBy, runId);
+        const args = { input, startedBy, ...(sandbox === undefined ? {} : { sandbox }), ...(hold && { hold }) };
+        const { onBehalfOf } = startedBy;
         // An id DBOS has already returns that run, unless it is another workflow's, which DBOS refuses.
         const handle = await this.dbos
             .enqueue({
@@ -105,8 +125,9 @@ export class SanomaClient {
             applicationName: this.config.appName,
             authenticatedUser: startedBy.id,
             authenticatedRoles: startedBy.groups ?? [],
-            // Kept on the run's status row too, so a listing tells sandbox runs apart without its input.
-            ...(sandbox === undefined ? {} : { attributes: { sandbox } }),
+            // 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).
+            ...((sandbox !== undefined || onBehalfOf !== undefined) && { attributes: { sandbox, onBehalfOf } }),
         }, args)
             .catch((err) => {
             if (runId !== undefined && err instanceof DBOSErrors.DBOSConflictingWorkflowError) {
@@ -119,6 +140,200 @@ export class SanomaClient {
             await this.mustMatch(runId, args);
         return handle.workflowID;
     }
+    /**
+     * 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.
+     */
+    async startHold(workflow, input, startedBy, runId) {
+        const { policy } = this.config;
+        if (BUILT_IN_WORKFLOWS.has(workflow) || policy === allowAll)
+            return undefined;
+        if (runId !== undefined && (await this.row(runId)))
+            return undefined;
+        const decision = decideStart(policy, workflow, input, startedBy);
+        if (decision.kind === "allow")
+            return undefined;
+        if (decision.kind === "deny")
+            throw new PolicyDeniedError(`${WORKFLOW_ACTION}${workflow}`, decision.reason);
+        return startHoldOf(workflow, decision);
+    }
+    /**
+     * Calls an operation directly, outside a run, as `actor`: one that may be (`isDirect`), a
+     * collection's or a vendor's read, never a vendor's write, the runtime's own or a resource
+     * type's (`invalid_input`, as is an unknown id or input its schema refuses). The policy decides
+     * it as the person, in a run `direct:<actor>:<id>` of the workflow `call` with no approvals. A
+     * deny throws `policy_denied` and writes nothing. An allowed call runs the driver once, without
+     * DBOS and without a retry (a driver's failure is `driver_failed`). A read returns its output
+     * and records nothing. A write is recorded as one `op.called` (seq 0) in that run, and with the
+     * default ledger in one transaction with the record it saves, so both are written or neither;
+     * a write with the same id and input returns the output recorded. When the policy asks for an
+     * approval, the call becomes run `call:<actor>:<id>` of the built-in `call` workflow, started
+     * as the person, which makes it once approved, and this throws `approval_pending` with its id.
+     */
+    async call(opId, input, options) {
+        const actor = await this.admitted(parseOrThrow(PrincipalOrId, options?.actor, '`actor` must be a principal, such as "alice" or { id: "alice" }'));
+        const id = parseOrThrow(z.string().min(1).optional(), options.id, "`id` must be a non-empty string") ?? randomUUID();
+        const { ops, types, drivers, policy } = this.config;
+        const op = ops.get(opId);
+        if (!op || !isDirect(op, types)) {
+            const why = op ? "it is a workflow's to call: start one that uses it" : "no connector or collection declares it";
+            throw new SanomaError("invalid_input", `${opId} cannot be called directly: ${why}`, { op: opId });
+        }
+        const fn = drivers.get(op.id);
+        if (!fn)
+            throw new SanomaError("invalid_input", `${op.id} has no driver: the connector package must attach one`);
+        const parsed = parseOrThrow(op.input, input, `The input to ${op.id} does not match its schema`, { op: op.id });
+        const runId = `direct:${actor.id}:${id}`;
+        const heldId = `call:${actor.id}:${id}`;
+        const held = { input: { op: op.id, input }, startedBy: actor };
+        const logged = recorded(op, parsed);
+        const write = op.effect !== "read";
+        // Only an id the caller gave can have been used: a write made, or held, with it settles it.
+        if (write && options.id !== undefined) {
+            const first = (await this.recordedCall(runId, op.id, logged)) ?? (await this.heldCall(op.id, heldId, held));
+            if (first)
+                return first.output;
+        }
+        const before = await beforeOf(policy, op, parsed, this.config.collections, (get, key) => drivers.get(get)?.({ key }, { idempotencyKey: `${runId}:before`, runId, opId: get, attempt: 1, secrets: this.storedSecrets, by: actor.id }));
+        const run = { id: runId, workflow: CALL_WORKFLOW, approvals: [] };
+        const decision = decideCall(policy, op, parsed, actor, run, before);
+        if (decision.kind === "deny")
+            throw new PolicyDeniedError(op.id, decision.reason);
+        if (decision.kind === "approve") {
+            await this.start(CALL_WORKFLOW, held.input, { startedBy: actor, runId: heldId });
+            // A read held before, whose run has ended since, answers with that run's result.
+            return (await this.heldCall(op.id, heldId, held)).output;
+        }
+        const context = {
+            idempotencyKey: runId,
+            runId,
+            opId: op.id,
+            attempt: 1,
+            secrets: this.storedSecrets,
+            by: actor.id,
+        };
+        if (!write)
+            return outputOf(op, () => fn(parsed, context));
+        return this.directWrite({ op, fn, parsed, logged, actor, decision, context });
+    }
+    /**
+     * A direct write, made once and recorded once: with the default ledger, a collection's write
+     * and its record in one transaction on the database both are in, so both are kept or neither;
+     * otherwise the driver's call, then the record in the config's ledger. The first record of the
+     * call's id stands: a write that finds one already there (two calls with one id at once) is
+     * undone, and answers as `recordedCall` does.
+     */
+    async directWrite(call) {
+        const { op, parsed, logged, actor, decision, context } = call;
+        const { runId } = context;
+        const { dataStore, collections, ledger } = this.config;
+        const conn = op.vendor === DATA_VENDOR && !ledger && dataStore ? await (await dataStore.db()).connect() : undefined;
+        let broken;
+        try {
+            await conn?.query("BEGIN");
+            // On the transaction's connection, the collection's own driver: it has no `env` to guard.
+            const fn = conn
+                ? collectionsDriver([collections.get(op.resource)], { db: async () => conn }).ops[`${op.resource}.${op.name}`]
+                : call.fn;
+            const at = Date.now();
+            const record = (outcome) => ({
+                v: 1,
+                app: this.config.appName,
+                id: `${runId}:op.called:0`,
+                runId,
+                seq: 0,
+                at,
+                actor,
+                workflow: CALL_WORKFLOW,
+                type: "op.called",
+                op: op.id,
+                effect: op.effect,
+                input: logged,
+                decision,
+                ...outcome,
+                durationMs: Date.now() - at,
+            });
+            let output;
+            try {
+                output = await outputOf(op, () => fn(parsed, context));
+            }
+            catch (err) {
+                // Recorded on the store's own connection; the transaction is rolled back below.
+                await this.audit.store.append(record({ error: errorInfo(err) }));
+                throw err;
+            }
+            const done = record({ output: recorded(op, output) });
+            if (!conn) {
+                await this.audit.store.append(done);
+                return output;
+            }
+            if (await insertRecord(conn, done)) {
+                await conn.query("COMMIT");
+                return output;
+            }
+            await conn.query("ROLLBACK");
+            return (await this.recordedCall(runId, op.id, logged)).output;
+        }
+        catch (err) {
+            await conn?.query("ROLLBACK").catch((e) => (broken = e));
+            throw err;
+        }
+        finally {
+            conn?.release(broken);
+        }
+    }
+    /**
+     * What the direct write recorded as `runId` returned, when one did: refused (`invalid_input`)
+     * when it was of another operation or input, and its failure again (`driver_failed`) when it failed.
+     */
+    async recordedCall(runId, opId, input) {
+        const first = (await this.audit.store.read(runId)).find((r) => r.type === "op.called");
+        if (!first)
+            return undefined;
+        const differs = [...(first.op === opId ? [] : ["op"]), ...(sameJson(first.input, input) ? [] : ["input"])];
+        if (differs.length) {
+            throw new SanomaError("invalid_input", `Call ${runId} was made already with a different ${differs.join(" and ")}; use another id`, { runId, differs });
+        }
+        if (first.error) {
+            throw new SanomaError("driver_failed", `${opId} failed when first called as ${runId}: ${first.error.message}; call again with another id`, {
+                runId,
+                op: opId,
+                error: first.error,
+            });
+        }
+        return { output: first.output };
+    }
+    /**
+     * What the held call's run `heldId` returned once it ended (its error, when it failed);
+     * `approval_pending` while it has not; undefined when there is no such run. Refused
+     * (`invalid_input`) when the run was started with another input or by someone else.
+     */
+    async heldCall(opId, heldId, args) {
+        const [row] = await this.dbos.listWorkflows({ workflowIDs: [heldId], loadInput: false, loadOutput: false });
+        if (!row)
+            return undefined;
+        await this.mustMatch(heldId, args);
+        if (!isEnded(runStatus(row.status, [])))
+            throw new ApprovalPendingError(opId, heldId);
+        return { output: await this.awaitResult(heldId, 30_000) };
+    }
+    /**
+     * The newest finished run of the workflow, with its output and when it finished; null when it
+     * has none. One query, whatever the app's runs.
+     */
+    async latest(workflow) {
+        const [row] = await this.dbos.listWorkflows({
+            workflowName: workflow,
+            applicationName: this.config.appName,
+            status: "SUCCESS",
+            sortDesc: true,
+            limit: 1,
+            loadInput: false,
+            loadOutput: true,
+        });
+        return row ? { runId: row.workflowID, output: row.output, at: row.updatedAt ?? row.createdAt } : null;
+    }
     /** The run's audit record, in order, from the ledger store. */
     async ledger(runId) {
         await this.mustExist(runId);
@@ -166,7 +381,9 @@ export class SanomaClient {
      * queued for the run, which reads it when it next runs.
      */
     async decide(runId, message, approvalId, options = {}) {
-        const msg = parseOrThrow(ApprovalMessage, message, "Not a decision");
+        const given = parseOrThrow(ApprovalMessage, message, "Not a decision");
+        const declared = readPeople(this.config.root);
+        const msg = { ...given, by: admit(given.by, declared) };
         // A run that does not exist has no approvals, so run_not_found never hides already_decided.
         const [all, row] = await Promise.all([this.approvals(runId), this.mustExist(runId)]);
         const target = approvalId ? all.find((a) => a.id === approvalId) : all.find((a) => a.status === "pending");
@@ -184,11 +401,13 @@ export class SanomaClient {
         if (!target) {
             throw new SanomaError("no_pending_approval", `Run ${runId} has no pending approval${approvalId ? ` "${approvalId}"` : ""}`, { runId, ...(approvalId ? { approvalId } : {}) });
         }
-        if (!mayDecide(target, msg.by)) {
-            throw new SanomaError("not_approver", `${notApprover(target, msg.by)} (${target.id})`, {
+        const reason = refusalOf(target, msg.by, { actor: row.authenticatedUser ? { id: row.authenticatedUser } : undefined }, declared.people);
+        if (reason !== undefined) {
+            throw new SanomaError("not_approver", `${reason} (${target.id})`, {
                 runId,
                 approvalId: target.id,
                 approver: target.approver,
+                reason,
             });
         }
         // The id names this message, so the run's answer says whether it decided with it, and is
@@ -215,6 +434,7 @@ export class SanomaClient {
                 runId,
                 approvalId: target.id,
                 approver: target.approver,
+                reason: refused.reason,
             });
         }
         if (now.status !== "pending" && now.decidedWith !== id)
@@ -235,39 +455,60 @@ export class SanomaClient {
      * `invalid_input` when the config's connectors declare no resource types, so it has none.
      */
     async drift(options) {
-        const drift = this.config.workflows.get(DRIFT_WORKFLOW);
-        if (!drift) {
-            throw new SanomaError("invalid_input", "The config's connectors declare no resource types, so there is nothing to check for drift");
-        }
-        return this.start(drift, {}, options);
+        return this.start(this.builtIn(DRIFT_WORKFLOW), {}, options);
+    }
+    /** The report of a drift run once it ends: as `applyReport` for apply. */
+    async driftReport(runId) {
+        return (await this.reportOf(runId, DRIFT_WORKFLOW));
+    }
+    /**
+     * Starts the built-in apply workflow, which reads the config's data files itself, with `input`
+     * (`only`, `bind`, `answers`; `{}` for all). Returns the run id; `applyReport` waits for its
+     * report. Throws `invalid_input` when the config's connectors declare no resource types.
+     */
+    async apply(input, options) {
+        return this.start(this.builtIn(APPLY_WORKFLOW), input, options);
     }
     /**
-     * The report of a drift run once it ends. Throws `run_not_found`, `invalid_input` for another
+     * The report of an apply run once it ends. Throws `run_not_found`, `invalid_input` for another
      * workflow's run, the run's error when it failed, and `run_running` when it has not ended
      * within 30 s.
      */
-    async driftReport(runId) {
+    async applyReport(runId) {
+        return (await this.reportOf(runId, APPLY_WORKFLOW));
+    }
+    /** The built-in workflow `name`; `invalid_input` when the config has none, as its connectors declare no resource types. */
+    builtIn(name) {
+        const workflow = this.config.workflows.get(name);
+        if (!workflow) {
+            throw new SanomaError("invalid_input", `The config's connectors declare no resource types, so it has no built-in ${name} workflow`);
+        }
+        return workflow;
+    }
+    /** The output of a run of the built-in `workflow` once it ends. */
+    async reportOf(runId, workflow) {
         const row = await this.mustExist(runId, { loadOutput: true });
-        if (row.workflowName !== DRIFT_WORKFLOW) {
-            throw new SanomaError("invalid_input", `Run ${runId} is a run of ${row.workflowName}, not of ${DRIFT_WORKFLOW}`, {
+        if (row.workflowName !== workflow) {
+            throw new SanomaError("invalid_input", `Run ${runId} is a run of ${row.workflowName}, not of ${workflow}`, {
                 runId,
                 workflow: row.workflowName,
             });
         }
         // A finished run's report came with its row; else wait for the run.
-        return (row.status === "SUCCESS" ? row.output : await this.awaitResult(runId, 30_000));
+        return row.status === "SUCCESS" ? row.output : await this.awaitResult(runId, 30_000);
     }
     /**
      * Stores a value for a variable a driver's `env` declares, as `by`, and tells the workers: each
      * loads it into its environment, unless its environment sets the variable itself. Refuses
      * (`invalid_input`) a name no driver declares, and a value the variable's schema refuses, with
      * the schema's reason and never the value; an empty value too (`clearCredential` unsets one).
-     * Nothing records the value but its row, which records `by` and when.
+     * Nothing records the value but its row, which records `by` and when. `by` is admitted as
+     * `start`'s `startedBy` is (`not_admitted`).
      */
     async setCredential(name, value, options) {
+        const setBy = await this.admittedBy(options);
         // Checked against every declaration of the name, as the worker checks it.
         const statuses = this.declared(name, (n) => (n === name ? value : undefined));
-        const setBy = actorOf(options);
         const refused = statuses.find((c) => c.status !== "set");
         if (refused) {
             const problem = refused.problem ?? "it is empty; clear it to unset it";
@@ -281,13 +522,49 @@ export class SanomaClient {
     /**
      * Deletes the stored value of a declared variable, and tells the workers, which unset it unless
      * their environment sets it. `by` is who asks; nothing records it once the row is gone.
-     * Refuses (`invalid_input`) a name no driver declares.
+     * Refuses (`invalid_input`) a name no driver declares, and `by` as `setCredential` does.
      */
     async clearCredential(name, options) {
+        await this.admittedBy(options);
         this.declared(name, () => undefined);
-        actorOf(options);
         await deleteCredential(await this.credentialsDb(), name);
     }
+    /**
+     * Stores a secret as `by`, and tells the workers: a value under any variable's name, declared by
+     * a driver or not, such as a data file's `secret("NAME")` or the app's own (its GitHub App's
+     * keys). A name a driver declares is checked as `setCredential` checks it; any other name must
+     * look like a variable's, and the value must not be empty (`invalid_input`, never the value).
+     */
+    async setSecret(name, value, options) {
+        if ([...credentialsOf(this.drivers, () => undefined).values()].flat().some((c) => c.name === name)) {
+            return this.setCredential(name, value, options);
+        }
+        const setBy = await this.admittedBy(options);
+        const problem = !VARIABLE.test(name) ? "That is not a variable name" : !value ? "Enter a value" : undefined;
+        if (problem) {
+            const path = VARIABLE.test(name) ? "value" : "name";
+            throw new SanomaError("invalid_input", problem, { issues: [{ path: [path], message: problem, code: "custom" }] });
+        }
+        await storeCredential(await this.credentialsDb(), { name, value, setBy });
+    }
+    /**
+     * The values of these secrets, as a driver's `secrets.get` reads them: this process's
+     * environment, which wins, else the stored value, with who set it and when. A name with neither
+     * is left out. For server code: a page is told whether one is set, never its value.
+     */
+    async secrets(names) {
+        const rows = await storedCredentials(await this.credentialsDb(), names);
+        const found = new Map();
+        for (const name of names) {
+            const env = process.env[name];
+            const row = rows.get(name);
+            if (env && env !== row?.value)
+                found.set(name, { value: env, source: "environment" });
+            else if (row)
+                found.set(name, { ...row, source: "stored" });
+        }
+        return found;
+    }
     /**
      * Each vendor's declared variables and their statuses now: from this process's environment,
      * which wins, else from the stored credentials, with `source` saying which (a value equal to
@@ -311,7 +588,12 @@ export class SanomaClient {
         return new Map([...statuses].map(([vendor, list]) => [vendor, list.map(sourced)]));
     }
     async close() {
-        await Promise.all([this.dbos.destroy(), this.credentialsPool.close(), this.audit.close()]);
+        await Promise.all([
+            this.dbos.destroy(),
+            this.credentialsPool.close(),
+            this.audit.close(),
+            this.config.dataStore?.close(),
+        ]);
     }
     /**
      * The name's statuses with `lookup`'s value, one per vendor whose drivers declare it, or
@@ -335,17 +617,36 @@ export class SanomaClient {
     credentialsDb() {
         return this.credentialsPool.db();
     }
+    /**
+     * The principal as the data files declare it (`admit`): its id alone is taken, never the groups
+     * a caller gives, and an id nobody declares is `not_admitted`.
+     */
+    async admitted(principal) {
+        return admit(principal, readPeople(this.config.root));
+    }
+    /** `options.by`, who sets or clears a credential, admitted (`admitted`): their id. */
+    async admittedBy(options) {
+        const by = parseOrThrow(z.string().min(1), options?.by, '`by` must name who is asking, such as "alice"');
+        return (await this.admitted({ id: by })).id;
+    }
     /** Refuses a run id whose run, as stored, was started with another input, by someone else, or in another sandbox. */
     async mustMatch(runId, args) {
         const [stored] = ((await this.dbos.getWorkflow(runId))?.input ?? []);
-        const differs = ["input", "startedBy", "sandbox"].filter((key) => !stored || !sameJson(stored[key], args[key]));
+        // Who started it by id alone: their groups are the people files' at the time, which may change.
+        const differs = ["input", "startedBy", "sandbox"].filter((key) => !stored ||
+            (key === "startedBy" ? stored.startedBy?.id !== args.startedBy.id : !sameJson(stored[key], args[key])));
         if (differs.length) {
             throw new SanomaError("invalid_input", `Run ${runId} already exists with a different ${differs.join(", ")}; use another run id`, { runId, differs });
         }
     }
-    /** The run's status row, read without its input (and its output, unless asked), or `run_not_found`. */
-    async mustExist(runId, { loadOutput = false } = {}) {
+    /** The run's status row, read without its input (and its output, unless asked), if there is one. */
+    async row(runId, { loadOutput = false } = {}) {
         const [row] = await this.dbos.listWorkflows({ workflowIDs: [runId], loadInput: false, loadOutput });
+        return row;
+    }
+    /** The run's status row, as `row` reads it, or `run_not_found`. */
+    async mustExist(runId, options = {}) {
+        const row = await this.row(runId, options);
         if (!row)
             throw new SanomaError("run_not_found", `No run ${runId}`, { runId });
         return row;
@@ -370,11 +671,18 @@ export class SanomaClient {
     async summarize(r) {
         const approvals = await this.approvals(r.workflowID);
         const groups = r.authenticatedRoles ?? [];
+        const onBehalfOf = r.attributes?.onBehalfOf;
         return {
             runId: r.workflowID,
             workflow: r.workflowName,
             status: runStatus(r.status, approvals),
-            startedBy: r.authenticatedUser ? { id: r.authenticatedUser, ...(groups.length ? { groups } : {}) } : undefined,
+            startedBy: r.authenticatedUser
+                ? {
+                    id: r.authenticatedUser,
+                    ...(groups.length ? { groups } : {}),
+                    ...(typeof onBehalfOf === "string" && { onBehalfOf }),
+                }
+                : undefined,
             createdAt: r.createdAt,
             updatedAt: r.updatedAt,
             approvals,
@@ -383,14 +691,27 @@ export class SanomaClient {
         };
     }
 }
+/**
+ * What a direct call's driver returned, as the operation's output schema parses it; a failure
+ * with none of the runtime's codes (a reply the schema refuses, an error the driver let escape)
+ * is `driver_failed`, naming the operation.
+ */
+async function outputOf(op, call) {
+    try {
+        return op.output.parse(await call());
+    }
+    catch (err) {
+        if (errorCode(err) !== undefined)
+            throw err;
+        throw new SanomaError("driver_failed", `${op.id} failed: ${errorMessage(err)}`, { op: op.id }, { cause: err });
+    }
+}
 /** The value as JSON reads it back: a Date as its string, undefined members gone. */
 const asJson = (v) => (v === undefined ? undefined : JSON.parse(JSON.stringify(v)));
 /** True when the two are the same JSON, whatever the order of their keys. */
 const sameJson = (a, b) => isDeepStrictEqual(asJson(a), asJson(b));
 /** What an environment variable's name looks like. */
 const VARIABLE = /^[A-Z_][A-Z0-9_]*$/;
-/** `options.by`, who sets or clears a credential: a name, or `invalid_input`. */
-const actorOf = (options) => parseOrThrow(z.string().min(1), options?.by, '`by` must name who is asking, such as "alice"');
 const alreadyDecided = (runId, a) => new SanomaError("already_decided", `${a.id} on run ${runId} was already ${a.status} by ${a.decidedBy}`, {
     runId,
     approvalId: a.id,