@alvera-ai/platform-sdk 0.15.0 → 0.16.1

package/.agent/cookbook/marketing-campaign-send.md

@@ -273,7 +273,7 @@ const ROSTER_MDM = `{% assign p = msg %}
   "legal_entity_type": "business",
   "business_name": "{{ p.business_name | json_escape }}",
   "identifiers": [
-    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ p.direct_customer_id | json_escape }}"}
+    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ p.direct_customer_id | json_escape }}", "type": "digital_identifier"}
   ]
 }`
 
@@ -376,7 +376,7 @@ const AUDIENCE_MDM = `{% assign p = msg %}
   {% if first_name != "" %}"first_name": "{{ first_name | json_escape }}",{% endif %}
   {% if last_name != "" %}"last_name": "{{ last_name | json_escape }}",{% endif %}
   "identifiers": [
-    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ handle | json_escape }}"}
+    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ handle | json_escape }}", "type": "digital_identifier"}
   ]
 }`
 
@@ -609,6 +609,7 @@ const { data: workflow } = await api.workflows.create(tenantSlug, datalakeSlug,
   dataset_type: 'generic_table',
   generic_table_id: ctx.audienceTableId,
   status: 'live',
+  tags: ['marketing', 'loyalty'],
   skip_mdm_resolution: false,
   filter_config: { type: 'custom', body: CAMPAIGN_FILTER, output_schema: { type: 'boolean' } },
   decision_config: {
@@ -690,7 +691,10 @@ const { data: run } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.work
   mode: 'live',
   manual_override: false,
 })
-ctx.runLogId = run.workflow_run_log_id!
+// run-workflow only SCHEDULES the run. The log id is written when it
+// fires, so read it back via workflowRuns.get.
+const fired = await ctx.waitForFiredRun(datalakeSlug, run.workflow_run_id)
+ctx.runLogId = fired.workflowRunLogId
 
 const deadline = Date.now() + 180_000
 let byStatus: Record<string, number> = {}
@@ -844,7 +848,7 @@ const REPLY_MDM = `{% assign p = msg %}
 {
   "legal_entity_type": "individual",
   "identifiers": [
-    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ p.handle | json_escape }}"}
+    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ p.handle | json_escape }}", "type": "digital_identifier"}
   ]
 }`
 
@@ -935,7 +939,7 @@ if (wfRow.status !== 'live') {
 }
 // Behavioural probe — a dry run against a selection no row can match:
 // the pipeline executes end-to-end, the final action call is
-// intercepted, and the acknowledgement carries the run-log id. The
+// intercepted, and the acknowledgement carries the scheduled run id. The
 // clause speaks this workflow's selection dialect: a GENERIC-TABLE
 // audience is addressed by its own columns (no `ra.` dataset alias —
 // that alias exists only for system-dataset selections).
@@ -944,8 +948,10 @@ const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx
   mode: 'dry_run',
   manual_override: false,
 })
-if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
-  throw new Error('dry-run probe returned no workflow_run_log_id')
+// The run-log id does not exist until the run fires — wait, do not read a null.
+const probeFired = await ctx.waitForFiredRun(datalakeSlug, probeRun.workflow_run_id)
+if (probeFired.workflowRunLogId.length === 0) {
+  throw new Error('dry-run probe never produced a workflow_run_log_id')
 }
 ```
 

package/.agent/cookbook/sanctions-screening-with-agent-review.md

@@ -270,6 +270,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
   description: 'Runs an LLM disambiguation pass on gray-zone-scored sanctions matches and fires a verdict-keyed SMS.',
   dataset_type: 'compliance_screening',
   status: 'live',
+  tags: ['compliance', 'sanctions'],
   filter_config: {
     type: 'custom',
     body: GRAY_ZONE_FILTER,
@@ -514,8 +515,11 @@ const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSl
   mode: 'live',
   manual_override: false,
 })
-ctx.runLogId = runResp.data.workflow_run_log_id!
-ctx.runBatchId = runResp.data.batch_id!
+// run-workflow only SCHEDULES the run. The log id and batch id are
+// written when it fires, so read them back via workflowRuns.get.
+const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
+ctx.runLogId = fired.workflowRunLogId
+ctx.runBatchId = fired.batchId!
 
 const deadline = Date.now() + 240_000
 let status: string | null = null
@@ -658,7 +662,7 @@ if (wfRow.status !== 'live') {
 }
 // Behavioural probe — a dry run against a selection no row can match:
 // the pipeline executes end-to-end, the final action call is
-// intercepted, and the acknowledgement carries the run-log id. The
+// intercepted, and the acknowledgement carries the scheduled run id. The
 // clause must speak this workflow's selection dialect — the dataset
 // alias is `rcs` here, the same alias the live run above uses.
 const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
@@ -666,8 +670,10 @@ const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx
   mode: 'dry_run',
   manual_override: false,
 })
-if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
-  throw new Error('dry-run probe returned no workflow_run_log_id')
+// The run-log id does not exist until the run fires — wait, do not read a null.
+const probeFired = await ctx.waitForFiredRun(datalakeSlug, probeRun.workflow_run_id)
+if (probeFired.workflowRunLogId.length === 0) {
+  throw new Error('dry-run probe never produced a workflow_run_log_id')
 }
 ```
 

package/.agent/cookbook/score-leads-with-llm-categorization.md

@@ -321,6 +321,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
   generic_table_id: genericTableId,
   skip_mdm_resolution: true,
   status: 'live',
+  tags: ['leads', 'llm'],
   filter_config: {
     type: 'custom',
     body: 'true',
@@ -486,8 +487,11 @@ const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSl
   mode: 'live',
   manual_override: true,
 })
-ctx.runLogId = runResp.data.workflow_run_log_id!
-ctx.runBatchId = runResp.data.batch_id!
+// run-workflow only SCHEDULES the run. The log id and batch id are
+// written when it fires, so read them back via workflowRuns.get.
+const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
+ctx.runLogId = fired.workflowRunLogId
+ctx.runBatchId = fired.batchId!
 
 const deadline = Date.now() + 240_000
 let status: string | null = null
@@ -564,7 +568,7 @@ if (wfRow.status !== 'live') {
 }
 // Behavioural probe — a dry run against a selection no row can match:
 // the pipeline executes end-to-end, the final action call is
-// intercepted, and the acknowledgement carries the run-log id. The
+// intercepted, and the acknowledgement carries the scheduled run id. The
 // clause speaks this workflow's selection dialect: a GENERIC-TABLE
 // dataset is addressed by its own columns (no `ra.` dataset alias —
 // that alias exists only for system-dataset selections).
@@ -573,8 +577,10 @@ const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx
   mode: 'dry_run',
   manual_override: false,
 })
-if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
-  throw new Error('dry-run probe returned no workflow_run_log_id')
+// The run-log id does not exist until the run fires — wait, do not read a null.
+const probeFired = await ctx.waitForFiredRun(datalakeSlug, probeRun.workflow_run_id)
+if (probeFired.workflowRunLogId.length === 0) {
+  throw new Error('dry-run probe never produced a workflow_run_log_id')
 }
 ```
 

package/.agent/cookbook/triage-prospects-by-priority.md

@@ -293,6 +293,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
   description: 'Bands AR customers into priority_high/medium/low via an LLM agent; one SMS action per band.',
   dataset_type: 'customer',
   status: 'live',
+  tags: ['ar', 'triage'],
   filter_config: {
     type: 'custom',
     body: '{% if customer.phone and customer.tax_id %}true{% endif %}',
@@ -422,8 +423,11 @@ const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSl
   mode: 'live',
   manual_override: true,
 })
-ctx.runLogId = runResp.data.workflow_run_log_id!
-ctx.runBatchId = runResp.data.batch_id!
+// run-workflow only SCHEDULES the run. The log id and batch id are
+// written when it fires, so read them back via workflowRuns.get.
+const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
+ctx.runLogId = fired.workflowRunLogId
+ctx.runBatchId = fired.batchId!
 
 const deadline = Date.now() + 240_000
 let status: string | null = null
@@ -497,14 +501,16 @@ if (wfRow.status !== 'live') {
 }
 // Behavioural probe — a dry run against a selection no row can match:
 // the pipeline executes end-to-end, the final action call is
-// intercepted, and the acknowledgement carries the run-log id.
+// intercepted, and the acknowledgement carries the scheduled run id.
 const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
   sql_where_clause: "ra.batch_id = 'test-never-matching-batch'",
   mode: 'dry_run',
   manual_override: false,
 })
-if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
-  throw new Error('dry-run probe returned no workflow_run_log_id')
+// The run-log id does not exist until the run fires — wait, do not read a null.
+const probeFired = await ctx.waitForFiredRun(datalakeSlug, probeRun.workflow_run_id)
+if (probeFired.workflowRunLogId.length === 0) {
+  throw new Error('dry-run probe never produced a workflow_run_log_id')
 }
 ```
 

package/.agent/cookbook/welcome-sms-for-customers.md

@@ -155,6 +155,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
   description: 'Sends a welcome SMS to newly contracted customers with a self-serve billing link.',
   dataset_type: 'customer',
   status: 'live',
+  tags: ['lifecycle', 'welcome'],
   filter_config: {
     type: 'custom',
     body: FILTER_BODY,
@@ -382,9 +383,11 @@ The SQL where-clause scopes the run to exactly the two batches
 exposes).
 
 The SMS action's `trigger_template: 'now'` dispatches the action
-immediately rather than scheduling it, so the run reaches a
-terminal status on its own — poll `batchLogs.refresh` until it
-leaves `:pending`. A `:partial` status is expected and fine here:
+immediately rather than deferring it, so once the run fires it
+reaches a terminal status on its own — poll `batchLogs.refresh`
+until it leaves `:pending`. The run itself is still scheduled:
+`workflows.run` records it and returns, which is why the setup
+file's `ctx.waitForFiredRun` sits between the call and the log id. A `:partial` status is expected and fine here:
 one row passed and one was filtered.
 
 ```typescript
@@ -393,8 +396,11 @@ const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSl
   mode: 'live',
   manual_override: false,
 })
-ctx.runLogId = runResp.data.workflow_run_log_id!
-ctx.runBatchId = runResp.data.batch_id!
+// run-workflow only SCHEDULES the run. The log id and batch id are
+// written when it fires, so read them back via workflowRuns.get.
+const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
+ctx.runLogId = fired.workflowRunLogId
+ctx.runBatchId = fired.batchId!
 
 const deadline = Date.now() + 120_000
 let status: string | null = null
@@ -537,14 +543,16 @@ if (wfRow.status !== 'live') {
 }
 // Behavioural probe — a dry run against a selection no row can match:
 // the pipeline executes end-to-end, the final action call is
-// intercepted, and the acknowledgement carries the run-log id.
+// intercepted, and the acknowledgement carries the scheduled run id.
 const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
   sql_where_clause: "ra.batch_id = 'test-never-matching-batch'",
   mode: 'dry_run',
   manual_override: false,
 })
-if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
-  throw new Error('dry-run probe returned no workflow_run_log_id')
+// The run-log id does not exist until the run fires — wait, do not read a null.
+const probeFired = await ctx.waitForFiredRun(datalakeSlug, probeRun.workflow_run_id)
+if (probeFired.workflowRunLogId.length === 0) {
+  throw new Error('dry-run probe never produced a workflow_run_log_id')
 }
 ```
 

package/.agent/errors.md

@@ -125,11 +125,17 @@ body):
     { "source": { "pointer": "/name" },
       "detail": "Missing field: name" },
     { "source": { "pointer": "/dataset_type" },
-      "detail": "Missing field: dataset_type" }
+      "detail": "Missing field: dataset_type" },
+    { "source": { "pointer": "/tags" },
+      "detail": "Missing field: tags" }
   ]
 }
 ```
 
+`tags` is the easy one to miss: it is required with no default, so
+omitting it 422s even though an empty list is a perfectly ordinary
+workflow. Send `tags: []` (see `workflows.md` §2).
+
 **Layer 1 — invalid enum value** (`dataset_type: "nonexistent_type"`):
 
 ```json

package/.agent/interoperability_contracts.md

@@ -168,6 +168,63 @@ generic_table_id  required UUID|null — required iff resource_type='generic_tab
 **Write-only (Request-only).** None — every caller-supplied field
 round-trips on the response.
 
+### What `mdm_input_config` must render — and the field that is easy to miss
+
+The body renders a JSON object describing the **subject** the row belongs
+to, so MDM can resolve it. The one part with a hard requirement that is not
+obvious from the shape is `identifiers`:
+
+```
+identifiers[]     uri       REQUIRED — the identifier's namespace
+                  type      REQUIRED — what kind of identifier it is
+                  value     REQUIRED — the identifier itself
+                  system    accepted, and NORMALISES ONTO `uri`
+                  country   optional — issuing country
+```
+
+**`type` is required and has no default.** An identifier with no type
+cannot be matched against anything, so MDM rejects the whole row:
+
+```
+MDM input validation failed
+reject_reason: %{identifiers: [%{type: ["can't be blank"]}]}
+```
+
+That rejection fails the contract at the `:mdm` stage, which means **the
+row never persists and the ingest looks silently empty** — you poll the
+dataset table and see zero rows, with nothing in the response to say why.
+Read the contract-stage failure to see the reason.
+
+`system` is accepted as an alias and normalises onto `uri`, so
+`{system, type, value}` and `{uri, type, value}` are both fine. What is
+never fine is omitting `type`.
+
+A worked example, from a green cookbook:
+
+```liquid
+{
+  "legal_entity_type": "individual",
+  "identifiers": [
+    {"system": "{{ p.source_uri }}", "value": "{{ handle }}", "type": "digital_identifier"}
+  ]
+}
+```
+
+**Do not confuse this with `identifications`,** which some `legal_entity`
+templates render into the record itself. That is a different embed with
+different keys (`id_type`, `uri`, `id_number`) — the two look alike and are
+not interchangeable.
+
+Two related shapes worth keeping straight:
+
+- **`mdm.verify`** (see `mdm.md`) takes looser input — it asks "is this
+  really you?" about an already-known subject, so it needs `value` plus a
+  `uri` **or** a `type`, not both. Its example is not a template for this
+  one.
+- **payments** additionally requires `id_type` on each entry of its own
+  verify payload. Per-domain differences are real; check the domain you are
+  writing for.
+
 ## 4. Error envelopes
 
 Standard JSON:API envelopes per `errors.md`. Common rejections:
@@ -178,6 +235,7 @@ Standard JSON:API envelopes per `errors.md`. Common rejections:
 | `/template_config/type`      | enum mismatch                                    |
 | `/template_config/body`      | empty when `type === 'custom'`                   |
 | `/mdm_input_config/type`     | enum mismatch                                    |
+| `identifiers[].type`         | blank — see §3; fails at the `:mdm` stage at INGEST time, not at create, so the contract saves fine and rows silently never land |
 | `/generic_table_id`          | missing when resource_type='generic_table',      |
 |                              | or non-null when not                             |
 | `/name`                      | uniqueness within datalake                       |

package/.agent/tools.md

@@ -74,6 +74,10 @@ the discriminator. Each branch is its own TypeScript type:
    tool_body_type = 'rest_api'       →  generic REST endpoint
    tool_body_type = 'sns'            →  AWS SNS topic (used for
                                         SMS / push notifications)
+   tool_body_type = 'twilio'         →  Twilio Programmable Messaging
+                                        (SMS). A first-class sender —
+                                        do NOT hand-author a rest_api
+                                        body for Twilio; see §2 below
    tool_body_type = 'end_user_messaging'
                                      →  AWS End User Messaging (used
                                         for MMS / media messages via
@@ -99,13 +103,103 @@ discriminator is a string-literal on each branch of the generated
 `ToolBodyWritable` union (`tool_body_type: 's3'`, `'rest_api'`, …).
 Consult the branch literals in
 `packages/sdk/src/generated/types.gen.ts` for the complete set,
-since new body types land independently of doc revisions. The
-platform declares the same twelve variants in
-`platform/lib/platform/tools/tool.ex` (`polymorphic_embeds_one(:body,
-…)`, lines 255–269).
+since new body types land independently of doc revisions.
 
 ## 2. Rules the type cannot encode
 
+### Twilio is a first-class sender — never hand-author `rest_api` for it
+
+Use `tool_body_type: 'twilio'`. Reaching for `intent: 'sms'` + a
+hand-authored `rest_api` body was the old workaround and it is now a
+mistake with a consequence: a `rest_api` Twilio sender has no
+`status_poller/twilio/…` path, so **the send can never learn what
+happened to it** — no delivery status, no reconciliation.
+
+```typescript
+await api.tools.create(tenantSlug, datalakeSlug, {
+  name: 'Campaign Sender — Main Line',
+  intent: 'sms',
+  tool_body_type: 'twilio',
+  variant_type: 'primary',
+  account_sid: 'AC…',           // "AC" + 32 hex
+  auth_token: '…',              // writeOnly — never comes back on a read
+  from_number: '+15550000001',  // XOR with messaging_service_sid
+  // base_url    — nullable; blank means https://api.twilio.com
+  // timeout_ms  — 1..300000, nullable
+  // base_message — ComplexTemplateConfig
+})
+```
+
+**`from_number` and `messaging_service_sid` are mutually exclusive.**
+Twilio resolves the messaging service and ignores `From` when both are
+sent, so a tool carrying both could no longer say which number a message
+went out on — and that join is the entire reason one tool exists per
+sender identity. The type permits both because the spec cannot express
+XOR; the server rejects it.
+
+There is deliberately **no `status_callback_url`**. The platform polls
+Twilio's Messages endpoint; a callback field would advertise a path that
+does not exist.
+
+### One credential, many senders: `variant_type` and `primary_tool_id`
+
+Every sender body — `twilio`, `sns`, `end_user_messaging`, `email` —
+declares which of two things it is:
+
+```
+variant_type = 'primary'   holds its own credential, borrows from nothing
+variant_type = 'variant'   borrows; primary_tool_id is REQUIRED
+```
+
+The problem this solves: one Twilio account behind three numbers used to
+mean three tools each holding the same `account_sid` and `auth_token`.
+Rotation was N edits, and a missed one is a **silent partial outage** —
+the other senders keep working, so nothing looks broken.
+
+**A variant stores no credential at all.** Reading one back, its
+`account_sid` / `api_key` / `access_key_id` / `smtp_*` come back `null`.
+**That is correct and complete, not missing data.** Do not "repair" it by
+copying the primary's credential in — that recreates the exact bug this
+removes. The platform resolves the primary at dispatch.
+
+**Rotation is one write, to the primary.** Any helper that "updates
+credentials across senders" is now wrong by construction: a partial
+rotation has no representation.
+
+**Depth is exactly one**, enforced by a database trigger rather than a
+changeset, because the rule reads another row. A violation is a **422
+with a field on it** — surface the message, do not retry:
+
+```
+names a tool that is itself a variant — a variant must name a primary
+names a tool of another type — a variant borrows from a primary of its own type
+names a primary on another provider — a variant borrows one account's credentials
+```
+
+What stays with the variant is the sender identity and its event routing:
+
+```
+twilio              from_number XOR messaging_service_sid
+sns                 phone_number
+end_user_messaging  phone_number · configuration_set_name
+email :mailgun      from_email · from_name · reply_to · domain
+email :ses          from_email · from_name · reply_to
+email :sendgrid     from_email · from_name · reply_to
+email :smtp         from_email · from_name · reply_to
+```
+
+Everything else — auth, region, endpoints, the MMS staging bucket — comes
+from the primary. Two entries look arbitrary and are not: Mailgun's
+`domain` is also a path segment in the request URL
+(`/v3/{domain}/messages`), and End User Messaging's
+`configuration_set_name` is the *event-routing* address, of which AWS
+permits one per originating number — a number that cannot name its own
+routing cannot be reconciled apart from its siblings.
+
+The split is per body type, and for Email per **provider**. That is the
+concrete reason there is no global credential registry: no single list
+could express it.
+
 ### `intent` and `tool_body_type` are loosely coupled
 
 The TypeScript type lets you combine any intent with any body
@@ -189,6 +283,48 @@ The full per-branch shape lives in
 `packages/sdk/src/generated/types.gen.ts` under the matching
 `Tool<Type>BodyWritable` types.
 
+### `assume_role` needs the platform's ARN — read it from `GET /api/ping`
+
+The `assume_role` auth method (on `sns` and `end_user_messaging`
+bodies) is configured from two values that come from opposite
+sides of the trust relationship:
+
+```
+   assume_role_arn          the role YOU create in YOUR AWS
+                              account, for the platform to assume
+   assume_role_external_id  the platform-generated external ID
+                              that role must require
+```
+
+Creating that role means naming a principal in its trust policy,
+and that principal is the platform's own IAM task role. It is
+readable from the unauthenticated health endpoint:
+
+```typescript
+const { data } = await api.ping()
+// data.iam_role_arn — e.g.
+//   'arn:aws:iam::123456789012:role/alvera-platform-task'
+```
+
+Three things to hold onto:
+
+- **`api.ping` takes no auth**, so the ARN is readable before a
+  session exists — onboarding flows and setup scripts can fetch it
+  on first contact with the platform.
+- **It differs per environment.** Read it from the environment you
+  are configuring against; never hardcode one and carry it across.
+- **It can be `null`.** Where the platform runs without AWS — the
+  normal case in local development — there is no task role to
+  trust. The generated `PingResponse` types `iam_role_arn` as
+  optional and `string | null` for exactly this reason, so handle
+  the null at every read rather than assuming a string.
+
+The ARN being public is deliberate: it has to reach every customer
+for onboarding to be possible. What stops a third party from
+pointing their own tool at your role is the
+`assume_role_external_id` — your trust policy must require that
+external ID, so possession of the ARN alone grants nothing.
+
 ### `status` field gates whether the tool can be invoked
 
 ```