@alvera-ai/platform-sdk 0.15.0 → 0.16.1

package/.agent/workflows.md

@@ -49,6 +49,7 @@ const { data: created } = await api.workflows.create(
     description: 'Send a review-request SMS after a fulfilled appointment',
     dataset_type: 'appointment',            // the dataset this workflow listens on
     status: 'live',                         // 'live' | 'draft' | 'manual' (see §5)
+    tags: ['appointments', 'sms'],          // REQUIRED on every write — [] if untagged (see §2)
     filter_config: {
       type: 'custom',
       body: `{% if appointment.source_uri == "12345.example.com" %}true{% endif %}`,
@@ -138,6 +139,25 @@ authors are Complex) — don't assume every `{ type, body }`-shaped config
 also carries a request-writable `output_schema`; check whether the field
 is pinned or caller-authored for that specific config before authoring one.
 
+### `tags` is required on every write, and has no default
+
+`tags` is a `string[]` on both the request and the response, and it is
+in `required:`. **Every `create()` / `update()` without it is a 422.**
+Send `tags: []` for an untagged workflow — the empty array is how you
+say "no tags", not something you can omit.
+
+The missing default is deliberate. `update()` is full-replacement (there
+is no PATCH, and no add-tag / remove-tag endpoint), so an omitted key
+cannot mean "leave tags alone". With a default, omitting it would have
+silently emptied a workflow's tags and returned 200. A 422 beats losing
+state the caller never mentioned.
+
+The labels are free text — no taxonomy, no shared vocabulary, and the
+execution pipeline does not read them. But they **do** participate in the
+workflow checksum, so retagging shifts the drift fingerprint. Re-tag and
+`checksum()` returns a different value even though nothing executable
+changed.
+
 ### `update()` replaces inline arrays whole
 
 `actions` and `context_datasets` are replaced whole by `update()`.
@@ -164,17 +184,34 @@ The placeholder names depend on the workflow's `dataset_type`
 appointment-driven workflow, customer_id + invoice.id for an
 invoice-driven workflow, etc.).
 
-### Scheduling lives on the ACTION, not on the run
+### Two scheduling levers, and they answer different questions
+
+There are **two**, and picking the wrong one is the most common mistake
+here:
+
+| lever | lives on | answers |
+|---|---|---|
+| `scheduled_at` | the **run** (`.run` body, §5) | *when is this send going out?* |
+| `trigger_template` | each **action** (below) | *when does this action fire, relative to the run?* |
+
+**`scheduled_at` is the one you want for a campaign.** A send time is
+per-send, not per-workflow: "this campaign goes Tuesday 9am" is a
+property of *this* send, and the next one goes at a different time. Pass
+`scheduled_at` on the run and leave the workflow definition alone.
 
-**The scheduling knob is `trigger_template` on each `action` — the
-`.run` / `.execute` calls carry no schedule field.** `.run` takes only
-`{ sql_where_clause, manual_override, mode }` (see §5); there is no
-`run_at`, no `schedule_for`. This is by design: you invoke the run
-*now*, every matched row is evaluated *now*, and each fired action then
-waits for its own `trigger_template` instant. "The platform can't
-schedule a campaign for Tuesday 9am" is the wrong conclusion — you
-schedule the *action* for Tuesday 9am and call `.run` whenever you
-like.
+**`trigger_template` is a property of the workflow itself** — "the
+reminder goes 24h before the appointment", "the follow-up goes 3 days
+after signup". It is relative to the run and belongs in the definition
+because it is true of every run.
+
+Use `trigger_template` for a campaign send time and you are rewriting the
+workflow before every send — a full `update()` per campaign, since
+`update()` replaces the resource whole. That was the only option before
+runs became a resource, and it is no longer the right answer.
+
+Neither lever is a guarantee of the instant a message leaves: the
+action window / quiet hours (below) can push an action later, and a
+`runtime_filter` can drop it entirely.
 
 ### `trigger_template` controls scheduling
 
@@ -322,6 +359,7 @@ are removed, and re-supplied ones are repositioned.
 await api.workflows.create(tenantSlug, datalakeSlug, {
   name: 'Contact-Us Triage',
   dataset_type: 'generic_table',
+  tags: [],
   // …other workflow fields…
   workflow_ai_agents: [
     {
@@ -412,6 +450,8 @@ name                         required string
 description                  optional string
 dataset_type                  required string — the dataset this listens on
 status                       required enum — 'live' | 'draft' | 'manual' (§5 Create)
+tags                         required array — string[]; NO default, send [] if
+                                              untagged; feeds the checksum (§2)
 generic_table_id              optional UUID — required iff dataset_type='generic_table'
 skip_mdm_resolution           optional bool — default false; a deliberate
                                               choice, NOT a generic-table default (§3)
@@ -486,39 +526,95 @@ are all `workflow_slug`-keyed). Passing a slug to `.get` 422s with
 
 ### Run
 
-`.run` evaluates the workflow against a SQL-selected row set. **The
-request body is exactly `{ sql_where_clause, manual_override, mode }` —
-there is no schedule field.** Scheduling is on each action's
-`trigger_template` (§2): `.run` fires the pipeline now; the actions it
-matches wait for their own trigger instants.
+**`.run` does not run the workflow. It records a run and returns.**
+The work happens when that run *fires* — immediately if you did not ask
+for a time, or at `scheduled_at` if you did.
 
 ```typescript
 const { data: run } = await api.workflows.run(
-  tenantSlug, workflowSlug,
+  tenantSlug, datalakeSlug, workflowSlug,
   {
     sql_where_clause: `ra.id = '${appointmentId}'`,  // run against the regulated tables
     mode: 'live',                                    // 'live' | 'dry_run'
     manual_override: false,                          // see below
+    scheduled_at: '2026-08-12T09:00:00+01:00',       // OPTIONAL — see below
   },
 )
-// run.batch_id              — tagged string (e.g. "manual:<uuid>");
-//                              the prefix distinguishes manual runs from
-//                              cron-driven ones
-// run.workflow_run_log_id   — UUID — the batch log row (poll via batchLogs)
-// run.enqueued_count        — number of rows the WHERE clause matched
-```
-
-**`.run`'s response envelope is fire-only — do not trust it to confirm
-success or failure.** `enqueued_count` (and any rendered-message field) can
-come back empty/`undefined` even when the run genuinely succeeded end to
-end — observed live: a manual run returned `enqueued_count: undefined` and
-a null message parse, yet its workflow execution log showed `filter: true`,
-the subject resolved, the action status was `completed`, and a real
-provider `external_id` came back (the SMS actually dispatched). The HTTP
-200 only means the run was *accepted*, not that you now know its outcome.
-**Always poll `workflow_run_log_id` via `batchLogs` + `workflowLogs`, and
-the action's own status, for the actual truth** — never branch logic on
-the immediate response body's counts or message fields.
+// run.workflow_run_id   — UUID of the run. This is the handle for
+//                          everything else: get, cancel, and the ids below.
+// run.status            — 'scheduled' | 'processing' | 'completed'
+//                          | 'cancelled' | 'failed'
+// run.scheduled_at      — when it will fire (always present; "now" is a
+//                          run scheduled for now, not a second code path)
+// run.matched_count     — nullable PREVIEW, see the warning below
+```
+
+**`batch_id`, `workflow_run_log_id` and `enqueued_count` are NOT on this
+response.** They described work that had not happened yet: the segment is
+resolved when the run fires, not when it is scheduled, so a run scheduled
+for Friday reaches Friday's rows. `batch_id` and `workflow_run_log_id`
+become readable from `workflowRuns.get` once the run has fired (below);
+`enqueued_count` has no replacement — count the rows the fan-out actually
+produced via `workflowLogs`, because a count column can claim three while
+nothing was inserted, and rows cannot.
+
+**`matched_count` is a preview, not the audience.** It is what the clause
+matched at schedule time, for sanity-checking the clause you just wrote.
+The segment is resolved *again* at send time with suppressed records
+excluded, so the number that actually goes out can be smaller. Never
+report `matched_count` to a user as "this many people will receive it".
+
+#### Scheduling a run
+
+`scheduled_at` is an ISO-8601 timestamp **with an offset**
+(`2026-08-12T09:00:00+01:00`). Omit it, or pass `null`, and the run fires
+as soon as a worker picks it up.
+
+It is **not** a guarantee of send time. Each action still passes through
+the workflow's action window and its own `trigger_template` (§2), so an
+action may execute later than the run fires — `scheduled_at` says when the
+segment is resolved and the fan-out begins, nothing more.
+
+#### Reading a run back — and the trap in it
+
+```typescript
+const { data: state } = await api.workflowRuns.get(tenantSlug, datalakeSlug, runId)
+```
+
+Poll until **`workflow_run_log_id` is a string** — *not* until `status`
+leaves `'scheduled'`. Those are different moments: the run reaches
+`processing` first and writes `workflow_run_log_id` and `batch_id` a beat
+later. A predicate on status alone releases you to read a `null`, and
+because `typeof null === 'object'` in JavaScript the symptom is a baffling
+*"expected string, got object"* rather than an obvious nil.
+
+Raise on `status === 'failed'` carrying `failure_reason` instead of
+polling to your deadline — a caller blocked on a run that will never fire
+should learn why on the first read, not thirty seconds later behind a
+generic timeout.
+
+**The HTTP 200 from `.run` means the run was *accepted*, not that you know
+its outcome.** For the actual truth, poll the run to get its
+`workflow_run_log_id`, then read `batchLogs` + `workflowLogs` and the
+action's own status. Never branch logic on the immediate response body.
+
+#### Listing and cancelling
+
+```typescript
+await api.workflowRuns.list(tenantSlug, datalakeSlug, { page: 1, page_size: 50 })
+await api.workflowRuns.cancel(tenantSlug, datalakeSlug, runId)
+```
+
+`list` is **datalake-scoped, not workflow-scoped** — it answers "what is
+going out from this datalake", across every workflow, which is the question
+a campaign screen actually asks. It takes the full Flop query surface
+(`page`, `page_size`, `order_by`, `order_directions`, `filters`).
+
+`cancel` is **refused once a run reaches `processing`**: the fan-out has
+begun and a job already executing cannot be stopped. Cancelling races the
+worker — both sides contend on one conditional update, so exactly one wins
+and the loser is told. Treat a refusal as a normal outcome to surface, not
+an error to retry.
 
 `sql_where_clause` accepts a fragment against the dataset's
 regulated tables (`ra` for appointments, `rp` for patients,
@@ -536,9 +632,11 @@ rejects stays rejected. (The platform pipeline discards the flag before
 filter and decision evaluation — override is not a "force through"
 switch.)
 
-A zero-match `sql_where_clause` still returns 200 and still
-creates a batch log row (`enqueued_count: 0`) — poll
-`workflow_run_log_id` uniformly, no special empty case.
+A zero-match `sql_where_clause` still returns 200 and still records a run
+that fires and writes a batch log row — poll `workflowRuns.get` for the
+`workflow_run_log_id` uniformly, no special empty case. At schedule time a
+zero-match clause reports `matched_count: 0`, but see the warning above:
+that is a preview of the clause, not proof that nothing was sent.
 
 ### Execute (per-row, per-action)
 
@@ -822,7 +920,8 @@ the datalake (live dispatch only):
 | enrichment | runs | runs |
 | action `runtime_filter` | applies | applies |
 | `manual_override` | dedupe/idempotency bypass only | same |
-| answers | `batch_id`, `workflow_run_log_id`, `enqueued_count` | `workflow_execution_log_id`, always `status: 'pending'` |
+| answers | `workflow_run_id`, `status`, `scheduled_at`, `matched_count` (the ids follow from `workflowRuns.get` once it fires) | `workflow_execution_log_id`, always `status: 'pending'` |
+| runs when | the run fires — now, or at `scheduled_at` | immediately |
 
 ### The three states a send can be in