@sanoma-ai/workflows 0.5.0 → 0.7.0

package/src/chats.ts

@@ -0,0 +1,114 @@
+import type { UIMessage } from "ai";
+import type { Pool } from "pg";
+import { CHAT_MESSAGES_TABLE as MESSAGES, CHATS_TABLE as CHATS } from "./db.ts";
+import { SanomaError } from "./errors.ts";
+
+// The operator agent's chats, in the config's database beside the runtime's other tables: one row
+// per chat (whose it is, the engine it runs on, the draft it edits) and its messages as the AI
+// SDK's UI messages. The turn itself is not durable: what a restart keeps is this transcript and
+// the draft's branch, and the person sends "continue".
+
+/** A chat as `SanomaClient.chats.list` reads it. */
+export interface Chat {
+  id: string;
+  /** Whose chat it is: the principal's id. Nobody else reads or continues it. */
+  person: string;
+  /** What runs its turns: `"loop"`, the app's own loop, or another engine the app knows. */
+  engine: string;
+  /** The draft it edits (`Source.draft`), once its first edit opened one. */
+  draftId?: string;
+  title: string;
+  /** When it was opened, in milliseconds since the epoch. */
+  createdAt: number;
+}
+
+/** The chats' store, `SanomaClient.chats`. */
+export interface Chats {
+  /**
+   * Opens the chat `id` (the browser's) for `person` on `engine`, titled `title`. An id another
+   * chat has is refused (`invalid_input`).
+   */
+  open(chat: { id: string; person: string; engine: string; title: string }): Promise<void>;
+  /** Records the draft the chat edits. */
+  attach(id: string, draftId: string): Promise<void>;
+  /**
+   * Writes these messages of the chat, each by its id: a message already there is replaced in its
+   * place, a new one goes after the rest, in the order given.
+   */
+  upsert(id: string, messages: readonly UIMessage[]): Promise<void>;
+  /** The chat's messages in order; none for a chat that has none. */
+  load(id: string): Promise<UIMessage[]>;
+  /** The chat `id`, or undefined when there is none. */
+  get(id: string): Promise<Chat | undefined>;
+  /** The person's chats, the newest first: the latest 50. */
+  list(person: string): Promise<Chat[]>;
+}
+
+/** A row of the chats' table. */
+interface ChatRow {
+  id: string;
+  person: string;
+  engine: string;
+  draft_id: string | null;
+  title: string;
+  created_at: Date;
+}
+
+const COLUMNS = "id, person, engine, draft_id, title, created_at";
+
+const chatOf = ({ draft_id, created_at, ...row }: ChatRow): Chat => ({
+  ...row,
+  ...(draft_id === null ? {} : { draftId: draft_id }),
+  createdAt: created_at.getTime(),
+});
+
+/** The chats' store on the pool `db` gives, the config's database once it is prepared. */
+export function chatStore(db: () => Promise<Pool>): Chats {
+  return {
+    async open({ id, person, engine, title }) {
+      const { rows } = await (
+        await db()
+      ).query(
+        `INSERT INTO ${CHATS} (id, person, engine, title) VALUES ($1, $2, $3, $4) ON CONFLICT (id) DO NOTHING RETURNING id`,
+        [id, person, engine, title],
+      );
+      if (!rows.length) throw new SanomaError("invalid_input", `Chat ${id} exists already; open it with another id`);
+    },
+    async attach(id, draftId) {
+      await (await db()).query(`UPDATE ${CHATS} SET draft_id = $2 WHERE id = $1`, [id, draftId]);
+    },
+    async upsert(id, messages) {
+      if (!messages.length) return;
+      if (messages.some((m) => !m.id)) throw new SanomaError("invalid_input", "A chat message needs an id");
+      // A new message's place is after the chat's last, in the order given.
+      await (
+        await db()
+      ).query(
+        `INSERT INTO ${MESSAGES} (chat_id, id, seq, message) ` +
+          `SELECT $1, m.value->>'id', last.seq + m.n, m.value ` +
+          `FROM jsonb_array_elements($2::jsonb) WITH ORDINALITY AS m (value, n), ` +
+          `(SELECT coalesce(max(seq), 0) AS seq FROM ${MESSAGES} WHERE chat_id = $1) AS last ` +
+          "ON CONFLICT (chat_id, id) DO UPDATE SET message = EXCLUDED.message",
+        [id, JSON.stringify(messages)],
+      );
+    },
+    async load(id) {
+      const { rows } = await (
+        await db()
+      ).query<{ message: UIMessage }>(`SELECT message FROM ${MESSAGES} WHERE chat_id = $1 ORDER BY seq, id`, [id]);
+      return rows.map((row) => row.message);
+    },
+    async get(id) {
+      const { rows } = await (await db()).query<ChatRow>(`SELECT ${COLUMNS} FROM ${CHATS} WHERE id = $1`, [id]);
+      return rows[0] && chatOf(rows[0]);
+    },
+    async list(person) {
+      const { rows } = await (
+        await db()
+      ).query<ChatRow>(`SELECT ${COLUMNS} FROM ${CHATS} WHERE person = $1 ORDER BY created_at DESC, id LIMIT 50`, [
+        person,
+      ]);
+      return rows.map(chatOf);
+    },
+  };
+}

package/src/client.ts

@@ -3,8 +3,17 @@ import { isDeepStrictEqual } from "node:util";
 import { type DBOSClient, Error as DBOSErrors, type WorkflowStatusString } from "@dbos-inc/dbos-sdk";
 import type { Pool } from "pg";
 import { z } from "zod";
-import { APPROVALS_EVENT, ApprovalMessage, decisionEventOf, messageKeyOf, topicOf } from "./approvals.ts";
+import {
+  APPROVALS_EVENT,
+  ApprovalMessage,
+  ApprovalWithdrawal,
+  decisionEventOf,
+  messageKeyOf,
+  topicOf,
+  withdrawalRefusal,
+} from "./approvals.ts";
 import { beforeOf, decideCall, decideStart, recorded, startHoldOf } from "./call.ts";
+import { type Chats, chatStore } from "./chats.ts";
 import { collectionsDriver } from "./collection.ts";
 import { type ResolvedConfig, resolveConfig, type SanomaConfig } from "./config.ts";
 import { deleteCredential, storeCredential, storedCredentials, storedSecrets } from "./credentials.ts";
@@ -39,6 +48,7 @@ import {
   isVisitor,
   refusalOf,
   type RunStatus,
+  SCHEDULE_AGENT,
   WORKFLOW_ACTION,
 } from "./shared.ts";
 
@@ -158,6 +168,22 @@ export interface CallOptions {
   id?: string;
 }
 
+/** What `SanomaClient.connect` is given besides the config. */
+export interface ClientOptions {
+  /**
+   * Called, never awaited, right before each change a worker must run: a run's start (drift,
+   * apply and a held call are starts) and an approval's decision or withdrawal; never for a read. A process that
+   * runs a worker that stops when idle starts it again with it (`Supervisor.resume`). Must not throw.
+   */
+  onWrite?: () => void;
+  /**
+   * The config as the caller resolved it (`resolveConfig(config, options)`), for a client that
+   * shares its drivers with the caller, as `startWorker`'s `resolved` does. The caller closes its
+   * `dataStore`.
+   */
+  resolved?: ResolvedConfig;
+}
+
 /** Talks to the runtime from another process (the app, a script), through the shared Postgres. */
 export class SanomaClient {
   private readonly dbos: DBOSClient;
@@ -165,18 +191,28 @@ export class SanomaClient {
   private readonly drivers: ReadonlyMap<string, Driver>;
   /** The config's own ledger store, or a Postgres one made for this client, which `close` then closes. */
   private readonly audit: OwnedLedger;
-  /** On the config's database, for the credentials table: opened on first use. */
-  private readonly credentialsPool: LazyPool;
+  /** On the config's database, for the runtime's tables (the credentials, the chats): opened on first use. */
+  private readonly pool: LazyPool;
   /** What a direct call's driver reads secrets from, as a worker's live driver does. */
   private readonly storedSecrets: Secrets;
+  /** The operator agent's chats: their rows and their transcripts, in the config's database. */
+  readonly chats: Chats;
+  private readonly options: ClientOptions;
 
-  private constructor(dbos: DBOSClient, config: ResolvedConfig, drivers: ReadonlyMap<string, Driver>) {
+  private constructor(
+    dbos: DBOSClient,
+    config: ResolvedConfig,
+    drivers: ReadonlyMap<string, Driver>,
+    options: ClientOptions,
+  ) {
     this.dbos = dbos;
     this.config = config;
     this.drivers = drivers;
+    this.options = options;
     this.audit = ownedLedger(config);
-    this.credentialsPool = lazyPool(config.databaseUrl, "credentials");
-    this.storedSecrets = storedSecrets(() => this.credentialsDb(), "sanoma");
+    this.pool = lazyPool(config.databaseUrl, "client");
+    this.storedSecrets = storedSecrets(() => this.db(), "sanoma");
+    this.chats = chatStore(() => this.db());
   }
 
   /**
@@ -184,10 +220,10 @@ export class SanomaClient {
    * what the worker would refuse. Reads ledgers from the config's ledger store, or from the
    * Postgres store on its database when it has none.
    */
-  static async connect(config: SanomaConfig): Promise<SanomaClient> {
-    const resolved = resolveConfig(config);
+  static async connect(config: SanomaConfig, options: ClientOptions = {}): Promise<SanomaClient> {
+    const resolved = options.resolved ?? resolveConfig(config);
     const dbos = await dbosClient(resolved.databaseUrl, resolved.appName);
-    return new SanomaClient(dbos, resolved, resolved.driversByVendor);
+    return new SanomaClient(dbos, resolved, resolved.driversByVendor, options);
   }
 
   /**
@@ -230,6 +266,7 @@ export class SanomaClient {
     const hold = await this.startHold(workflow.name, parsed, startedBy, runId);
     const args: RunArgs = { input, startedBy, ...(sandbox === undefined ? {} : { sandbox }), ...(hold && { hold }) };
     const { onBehalfOf } = startedBy;
+    this.options.onWrite?.();
     // An id DBOS has already returns that run, unless it is another workflow's, which DBOS refuses.
     const handle = await this.dbos
       .enqueue(
@@ -552,6 +589,53 @@ export class SanomaClient {
     const given = parseOrThrow(ApprovalMessage, message, "Not a decision");
     const declared = readPeople(this.config.root);
     const msg = { ...given, by: admit(given.by, declared) };
+    const { target, row } = await this.pendingApproval(runId, approvalId);
+    const reason = refusalOf(
+      target,
+      msg.by,
+      { actor: row.authenticatedUser ? { id: row.authenticatedUser } : undefined },
+      declared.people,
+    );
+    if (reason !== undefined) throw notApprover(runId, target, reason);
+    // The id names this message, so the run's answer says whether it decided with it, and is
+    // in its idempotency key, so a retried send queues it once.
+    const id = msg.id ?? randomUUID();
+    return this.sendToApproval(runId, target, { ...msg, id }, options.timeoutSeconds);
+  }
+
+  /**
+   * Withdraws the run's pending approval `approvalId`, saying `reason`, as `options.by`: the run's
+   * starter, or someone who may decide it (`not_approver` otherwise, here and again in the run,
+   * which records who withdrew it). The run reads the
+   * withdrawal as a decision, and the step that waits on it throws `approval_withdrawn`. Returns
+   * the approval as withdrawn, and refuses as `decide` does: `already_decided` when it is not
+   * pending (or another decision reached the run first), `run_ended`, `no_pending_approval`,
+   * `run_not_found`; and returns it still `pending` when the run does not read the withdrawal
+   * within `timeoutSeconds` (30 by default).
+   */
+  async withdraw(
+    runId: string,
+    approvalId: string,
+    reason: string,
+    options: { by: Principal | string; timeoutSeconds?: number },
+  ): Promise<ApprovalState> {
+    const withdraw = parseOrThrow(ApprovalWithdrawal.shape.withdraw, reason, "A withdrawal needs a reason");
+    const by = await this.admitted(
+      parseOrThrow(PrincipalOrId, options?.by, '`by` must be a principal, such as "alice" or { id: "alice" }'),
+    );
+    const { target, row } = await this.pendingApproval(runId, approvalId);
+    const refusal = withdrawalRefusal(target, by, row.authenticatedUser);
+    if (refusal !== undefined) throw notApprover(runId, target, refusal);
+    const id = randomUUID();
+    return this.sendToApproval(runId, target, { withdraw, by, id }, options.timeoutSeconds);
+  }
+
+  /**
+   * The run's approval `approvalId` (else its first pending one) and the run's row, when the
+   * approval is pending on a run that has not ended: `already_decided`, `run_ended`,
+   * `no_pending_approval` or `run_not_found` otherwise.
+   */
+  private async pendingApproval(runId: string, approvalId: string | undefined) {
     // 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");
@@ -572,28 +656,26 @@ export class SanomaClient {
         { runId, ...(approvalId ? { approvalId } : {}) },
       );
     }
-    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
-    // in its idempotency key, so a retried send queues it once.
-    const id = msg.id ?? randomUUID();
-    await this.dbos.send(runId, { ...msg, id }, topicOf(target.id), messageKeyOf(target.id, id));
+    return { target, row };
+  }
+
+  /**
+   * Sends a message with an `id` to the approval and waits up to `timeoutSeconds` (30 by
+   * default) for the run to read it: the approval as the run then has it, still `pending` if it
+   * has not read it. `not_approver` when the run refused it, `already_decided` when another
+   * message decided it first.
+   */
+  private async sendToApproval(
+    runId: string,
+    target: ApprovalState,
+    message: (ApprovalMessage | ApprovalWithdrawal) & { id: string },
+    timeoutSeconds = 30,
+  ): Promise<ApprovalState> {
+    this.options.onWrite?.();
+    await this.dbos.send(runId, message, topicOf(target.id), messageKeyOf(target.id, message.id));
     // DBOSClient does not LISTEN for events: it polls, every 10 s unless told otherwise. A
     // running worker answers within moments, so poll often at first, then once a second.
     const event = decisionEventOf(target.id);
-    const timeoutSeconds = options.timeoutSeconds ?? 30;
     const soon = Math.min(2, timeoutSeconds);
     const decided =
       (await this.dbos.getEvent<ApprovalState>(runId, event, { timeoutSeconds: soon, pollingIntervalMs: 100 })) ??
@@ -605,16 +687,10 @@ export class SanomaClient {
         : null);
     const now = decided ?? (await this.approvals(runId)).find((a) => a.id === target.id) ?? target;
     // Read, but refused: the run checks the sender again, and said no.
-    const refused = now.refused.find((r) => r.id === id);
-    if (refused) {
-      throw new SanomaError("not_approver", `${refused.reason} (${target.id})`, {
-        runId,
-        approvalId: target.id,
-        approver: target.approver,
-        reason: refused.reason,
-      });
-    }
-    if (now.status !== "pending" && now.decidedWith !== id) throw alreadyDecided(runId, now);
+    const refused = now.refused.find((r) => r.id === message.id);
+    if (refused) throw notApprover(runId, target, refused.reason);
+    // Another message reached the run first.
+    if (now.status !== "pending" && now.decidedWith !== message.id) throw alreadyDecided(runId, now);
     return now;
   }
 
@@ -704,7 +780,7 @@ export class SanomaClient {
         issues: [{ path: ["value"], message: problem, code: "custom" }],
       });
     }
-    await storeCredential(await this.credentialsDb(), { name, value, setBy });
+    await storeCredential(await this.db(), { name, value, setBy });
   }
 
   /**
@@ -715,7 +791,7 @@ export class SanomaClient {
   async clearCredential(name: string, options: { by: string }): Promise<void> {
     await this.admittedBy(options);
     this.declared(name, () => undefined);
-    await deleteCredential(await this.credentialsDb(), name);
+    await deleteCredential(await this.db(), name);
   }
 
   /**
@@ -734,7 +810,7 @@ export class SanomaClient {
       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 });
+    await storeCredential(await this.db(), { name, value, setBy });
   }
 
   /**
@@ -743,7 +819,7 @@ export class SanomaClient {
    * is left out. For server code: a page is told whether one is set, never its value.
    */
   async secrets(names: readonly string[]): Promise<Map<string, StoredSecret>> {
-    const rows = await storedCredentials(await this.credentialsDb(), names);
+    const rows = await storedCredentials(await this.db(), names);
     const found = new Map<string, StoredSecret>();
     for (const name of names) {
       const env = process.env[name];
@@ -763,7 +839,7 @@ export class SanomaClient {
   async credentials(): Promise<Map<string, CredentialStatus[]>> {
     const names = [...credentialsOf(this.drivers, () => undefined).values()].flat().map((c) => c.name);
     if (!names.length) return new Map();
-    const rows = await storedCredentials(await this.credentialsDb(), names);
+    const rows = await storedCredentials(await this.db(), names);
     const statuses = credentialsOf(this.drivers, (name) => process.env[name] || rows.get(name)?.value);
     const sourced = (c: CredentialStatus): CredentialStatus => {
       const row = rows.get(c.name);
@@ -778,9 +854,9 @@ export class SanomaClient {
   async close() {
     await Promise.all([
       this.dbos.destroy(),
-      this.credentialsPool.close(),
+      this.pool.close(),
       this.audit.close(),
-      this.config.dataStore?.close(),
+      this.options.resolved ? undefined : this.config.dataStore?.close(),
     ]);
   }
 
@@ -804,9 +880,9 @@ export class SanomaClient {
     });
   }
 
-  /** The pool the credentials are read and written with, on the database once it is prepared. */
-  private credentialsDb(): Promise<Pool> {
-    return this.credentialsPool.db();
+  /** The pool the runtime's tables are read and written with, on the database once it is prepared. */
+  private db(): Promise<Pool> {
+    return this.pool.db();
   }
 
   /**
@@ -883,6 +959,7 @@ export class SanomaClient {
     authenticatedRoles?: string[];
     error?: unknown;
     attributes?: Record<string, unknown>;
+    scheduleName?: string;
   }): Promise<RunSummary> {
     const approvals = await this.approvals(r.workflowID);
     const groups = r.authenticatedRoles ?? [];
@@ -897,7 +974,10 @@ export class SanomaClient {
             ...(groups.length ? { groups } : {}),
             ...(typeof onBehalfOf === "string" && { onBehalfOf }),
           }
-        : undefined,
+        : // DBOS enqueues a schedule's tick as nobody; the run starts as the schedule's agent.
+          r.scheduleName
+          ? { id: SCHEDULE_AGENT }
+          : undefined,
       createdAt: r.createdAt,
       updatedAt: r.updatedAt,
       approvals,
@@ -940,9 +1020,19 @@ export interface StoredSecret {
 const VARIABLE = /^[A-Z_][A-Z0-9_]*$/;
 
 const alreadyDecided = (runId: string, a: ApprovalState) =>
-  new SanomaError("already_decided", `${a.id} on run ${runId} was already ${a.status} by ${a.decidedBy}`, {
-    runId,
-    approvalId: a.id,
-    status: a.status,
-    decidedBy: a.decidedBy,
-  });
+  new SanomaError(
+    "already_decided",
+    a.status === "withdrawn"
+      ? `${a.id} on run ${runId} was already withdrawn: ${a.withdrawnReason}`
+      : `${a.id} on run ${runId} was already ${a.status} by ${a.decidedBy}`,
+    {
+      runId,
+      approvalId: a.id,
+      status: a.status,
+      ...(a.decidedBy === undefined ? {} : { decidedBy: a.decidedBy }),
+      ...(a.withdrawnReason === undefined ? {} : { withdrawnReason: a.withdrawnReason }),
+    },
+  );
+
+const notApprover = (runId: string, a: ApprovalState, reason: string) =>
+  new SanomaError("not_approver", `${reason} (${a.id})`, { runId, approvalId: a.id, approver: a.approver, reason });