@alvera-ai/platform-sdk 0.13.0 → 0.15.0

package/.agent/account_management.md

@@ -102,6 +102,37 @@ app authenticates **tenant-scoped against exactly one tenant**,
 with that tenant's publishable key; connected apps in particular
 are single-tenant by construction (`connected_apps.md`).
 
+### Key-only clients — machine-to-machine on the publishable key
+
+`sessionToken` is optional on the client config. A deployed
+connected app that authenticates purely on its tenant's publishable
+key constructs with just the key — no session mint, no fabricated
+empty token:
+
+```typescript
+const api = createIsolatedPlatformApi({ baseUrl, apiKey })
+```
+
+Such a client sends `X-API-Key` and **no `Authorization` header**,
+and reaches exactly the `public_api` (publishable-key) allowlist —
+five calls:
+
+```
+   api.connectedApps.resolvePage             mint/read a delivered page
+   api.connectedApps.updateMessageTracking   opened_at / form_submitted_at
+   api.dataActivationClients.ingest          submit rows
+   api.dataActivationClients.ingestFile      submit a file
+   api.mdm.verify                            resolve an identity
+```
+
+(The same allowlist `connected_apps.md` documents — that guide owns
+the runtime-call details.) Every call outside these five returns
+401; that ceiling is the point, not an error to work around.
+Minting a session and passing `sessionToken` unlocks the full
+tenant-scoped API exactly as before — the two credentials are
+complementary (the key identifies the client; the Bearer
+authorizes), never substitutes.
+
 ### Explicit teardown — `revokeSession`
 
 The inverse of `createSession`. Revokes the current Bearer on

package/.agent/action_status_updaters.md

@@ -40,8 +40,8 @@ const { data: created } = await api.actionStatusUpdaters.create(
     updater_body: {
       updater_body_type: 'cloud_watch_request',
       log_group_name: 'sns/us-east-1/...',
-      start_time: '{{ now | minutes_ago: 45 }}',     // Liquid window
-      end_time:   '{{ now }}',
+      start_time: '{{ now_msec | minutes_ago: 45 }}', // Liquid window
+      end_time:   '{{ now_msec }}',
     },
 
     // Liquid, rendered ONCE PER EVENT — the event IS the assigns, so there is no
@@ -51,6 +51,14 @@ const { data: created } = await api.actionStatusUpdaters.create(
       type: 'custom',
       body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
     },
+
+    // REQUIRED on every updater, both types, on create AND update. Same
+    // per-event rendering contract as `message_config`, but targets the
+    // action_log row instead of the message row.
+    action_log_config: {
+      type: 'custom',
+      body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
+    },
   },
 )
 ```
@@ -74,22 +82,30 @@ updater_body_type: 'cloud_watch_request'
 follow the same `<verb>_request` naming and carry the fields
 their target API requires.)
 
+`updater_body_type: 'restapi_request'` additionally **requires an
+`events_template` field**. Without it the REST poll fails with
+`missing_events_template`. `events_template` is specific to the REST
+poll's event-list extraction — it is not read by data-activation
+fetches.
+
 `start_time` / `end_time` are Liquid, and they **must render to
-unix milliseconds** — that is what the poll request takes. On
-these two fields `now` is a **variable already holding unix ms**,
-so pipe it through the relative-time filters:
+unix milliseconds** — that is what the poll request takes. Use the
+**`now_msec`** variable (unix ms) and pipe it through the
+relative-time filters. **Not the bare `now`** — that is a DateTime,
+and feeding it a millisecond filter now raises at render:
 
 ```
-start_time: '{{ now | minutes_ago: 45 }}'    // 45 minutes back
-end_time:   '{{ now }}'                       // right now
+start_time: '{{ now_msec | minutes_ago: 45 }}'    // 45 minutes back
+end_time:   '{{ now_msec }}'                       // right now
 ```
 
 Also available: `hours_ago: N`.
 
-**Do not use the ISO-8601 `now` filter here.** `{{ "" | now }}` is
-a different thing — it renders a datetime *string*, which is not a
-valid window, and the platform rejects it at create. An ISO 8601
-literal is not valid on these fields either.
+**Do not use the bare `now` variable or the ISO-8601 `now` filter
+here.** The `now` variable is a DateTime and `{{ "" | now }}`
+renders a datetime *string* — neither is a valid unix-ms window,
+and the platform rejects both. An ISO 8601 literal is not valid on
+these fields either.
 
 ### `message_config.body` renders ONCE PER EVENT
 
@@ -101,6 +117,10 @@ scope — do not loop.
 {"external_id": "{{ notification.messageId }}", "status": "delivered"}
 ```
 
+> **Shape only — do not copy this mapping.** A hardcoded `"delivered"`
+> records every event as delivered, failures included. Real bodies
+> branch on the provider's status; see the SNS and MMS sections below.
+
 It must render a **flat** JSON object:
 
 ```
@@ -123,6 +143,174 @@ events for messages this updater doesn't own.
 Custom Liquid filters (`json_escape`, `e164`, `to_json`, ...) are
 available here, as everywhere.
 
+### SMS-over-SNS delivery tracking — two `custom` bodies
+
+The SNS SMS delivery receipt is **binary and single-shot**: one terminal
+outcome, `status` of `SUCCESS` or `FAILURE`. Its event shape is
+**disjoint from EUM's** — `status`, `notification.messageId`,
+`notification.timestamp`, `delivery.phoneCarrier`,
+`delivery.providerResponse` all sit at the root. Do not carry an EUM
+template over to SNS or vice versa.
+
+Two convenient consequences, both unlike MMS:
+
+- `delivered_at` is `notification.timestamp` — a UTC
+  `"YYYY-MM-DD HH:MM:SS.sss"` string Ecto casts directly, so **no date
+  filter is needed** (EUM needs `from_unix_ms` on its Unix-ms field).
+- the DLR **does** surface the US carrier as `delivery.phoneCarrier`.
+
+**`message_config`:**
+
+```liquid
+{"external_id": "{{ notification.messageId }}", "status": "{% if status == 'SUCCESS' %}delivered{% else %}failed{% endif %}", "status_description": "{{ delivery.providerResponse | json_escape }}"{% if status == 'SUCCESS' and notification.timestamp %}, "delivered_at": "{{ notification.timestamp }}"{% endif %}{% unless status == 'SUCCESS' %}, "failure_reason": "{{ status | json_escape }}"{% endunless %}{% if delivery.phoneCarrier and delivery.phoneCarrier != '' %}, "sms_carrier": "{{ delivery.phoneCarrier | json_escape }}"{% endif %}}
+```
+
+**`action_log_config`:**
+
+```liquid
+{"external_id": "{{ notification.messageId }}", "status": "{% if status == 'SUCCESS' %}delivered{% else %}failed{% endif %}", "status_description": "{{ delivery.providerResponse | json_escape }}"}
+```
+
+`status_description` is `delivery.providerResponse` verbatim on both
+sides — the carrier's own text, on success and failure alike. Because
+SNS's status is binary, `failure_reason` can only ever be `"FAILURE"`;
+the granular carrier text stays in `status_description`.
+
+**Note how the two SNS bodies differ from each other**: same status
+mapping, fewer emitted fields on the action log (no `delivered_at`,
+`sms_carrier`, or `failure_reason` — those are message concerns). That
+is a *different* reason from MMS's, where the two also disagree on the
+mapping itself. Both channels need two bodies; they need them for
+different reasons.
+
+### MMS delivery tracking needs TWO different templates — author both as `custom`
+
+MMS delivery tracking is a `cloud_watch` updater. Author **both**
+`message_config` and `action_log_config` as `custom` bodies — the two
+render *different* JSON from the same event, so one body cannot serve
+both. This is the single most-missed thing about updaters.
+
+**Why they differ.** A message's status vocabulary includes
+`customer_rejected`; an action log's does not. A recipient or carrier
+rejection (`SPAM` / `BLOCKED` / `CARRIER_BLOCKED`) is a message-level
+outcome — the action *did* deliver — so the action-log render must
+**NO-OP** on those events while the message render records
+`customer_rejected`. The message side also carries `delivered_at`,
+`failure_reason`, and `sms_carrier`; only `status` +
+`status_description` are ever applied to an action log.
+
+AWS End User Messaging (`sms-voice`) event fields: top-level
+`messageId`, `eventType` (`MEDIA_*`), `messageStatus`,
+`messageStatusDescription`, `eventTimestamp` (Unix ms), `isFinal`.
+
+**`message_config`** — map every status, emit the extra fields:
+
+```liquid
+{% case messageStatus %}
+{% when 'DELIVERED' %}{% assign mapped_status = 'delivered' %}
+{% when 'SUCCESSFUL' %}{% assign mapped_status = 'sent' %}
+{% when 'PENDING' %}{% assign mapped_status = 'sent' %}
+{% when 'QUEUED' %}{% assign mapped_status = 'queued' %}
+{% when 'SPAM' %}{% assign mapped_status = 'customer_rejected' %}
+{% when 'BLOCKED' %}{% assign mapped_status = 'customer_rejected' %}
+{% when 'CARRIER_BLOCKED' %}{% assign mapped_status = 'customer_rejected' %}
+{% else %}{% assign mapped_status = 'failed' %}
+{% endcase %}
+{"external_id": "{{ messageId }}", "status": "{{ mapped_status }}", "status_description": "{{ messageStatusDescription | json_escape }}"{% if messageStatus == 'DELIVERED' and eventTimestamp %}, "delivered_at": "{{ eventTimestamp | from_unix_ms }}"{% endif %}{% if mapped_status == 'failed' or mapped_status == 'customer_rejected' %}, "failure_reason": "{{ messageStatus | json_escape }}"{% endif %}{% if carrierName and carrierName != '' %}, "sms_carrier": "{{ carrierName | json_escape }}"{% endif %}}
+```
+
+**`action_log_config`** — the rejection statuses fall through to a
+bare `external_id`, which applies nothing:
+
+```liquid
+{% assign al_status = '' %}{% case messageStatus %}{% when 'DELIVERED' %}{% assign al_status = 'delivered' %}{% when 'SUCCESSFUL' %}{% assign al_status = 'sent' %}{% when 'PENDING' %}{% assign al_status = 'sent' %}{% when 'QUEUED' %}{% assign al_status = 'queued' %}{% when 'SPAM', 'BLOCKED', 'CARRIER_BLOCKED' %}{% else %}{% assign al_status = 'failed' %}{% endcase %}{"external_id": "{{ messageId }}"{% if al_status != '' %}, "status": "{{ al_status }}", "status_description": "{{ messageStatusDescription | json_escape }}"{% endif %}}
+```
+
+Note the `{% when 'SPAM', 'BLOCKED', 'CARRIER_BLOCKED' %}` arm is
+deliberately **empty** — it leaves `al_status` blank, so the render
+emits `external_id` alone and the action log is untouched.
+
+**Capture every event, not just the terminal one.** 2–3 events arrive
+per message — interim `MEDIA_QUEUED` / `MEDIA_PENDING` /
+`MEDIA_SUCCESSFUL` (`isFinal: false`), then one terminal event
+(`isFinal: true`), up to 72h late and out of order. Apply is
+idempotent and a monotonic guard only ever advances `status`, so a
+late or interim lower-rank event can never demote a message that
+already reached a higher state. Poll a window that overlaps
+deliberately; nothing is dropped.
+
+`queued_at` and `sent_at` are **your outbound pipeline's** times, set
+when the platform enqueues and dispatches — a delivery poll never
+overwrites them. Only `delivered_at` comes from the carrier event
+(`DELIVERED`'s own `eventTimestamp` via `from_unix_ms`), so
+re-polling a wide window does not drift it.
+
+### Carrier information is available for SMS, not MMS
+
+The recipient's mobile carrier is present on SMS delivery events but
+not MMS. This is AWS behavior — verified against real delivery
+events — not something the platform chooses to drop:
+
+- **SMS via Amazon SNS** — the delivery-status log
+  (`sns/<region>/<account>/DirectPublishToPhoneNumber`) nests carrier
+  under `delivery.phoneCarrier` (e.g. `"T-mobile USA Inc."`, with
+  numeric `mcc`/`mnc`). The SNS status template maps it to
+  `sms_carrier`.
+- **MMS via AWS End User Messaging (`sms-voice`)** — the event *can*
+  carry `carrierName`, but it is DLR-populated and comes back
+  **absent for US destinations** (the US DLR does not surface it),
+  unlike the SNS path's `phoneCarrier`, whose US DLR does. So map it
+  when present — `{% if carrierName and carrierName != '' %}` — and
+  expect `sms_carrier` to stay null for US long-code traffic.
+  Verified against real AWS delivery events: the terminal
+  `MEDIA_DELIVERED` event for a US destination exposes
+  `totalCarrierFee` (a cost) and no `carrierName`.
+
+AWS's Nov-2024 EventBridge-integration announcement states MMS
+delivery events carry carrier information in EventBridge, but the
+real events do not — a documented doc-vs-behavior discrepancy. For
+per-number US carrier, use `PhoneNumberValidate` (returns `Carrier` +
+`PhoneType`) at enrollment and join on destination/`messageId`; it is
+not in the delivery stream.
+
+### `action_log_config` is required — same rendering contract as `message_config`
+
+`action_log_config` is a **required** field on every action status
+updater — `cloud_watch` and `restapi` alike — on **both `create()` and
+`update()`**. There is no updater for which it is optional and no way
+to omit it on a PUT.
+
+It follows the same per-event rendering contract as `message_config`
+(§2 above), but targets the **action_log** row instead of the message
+row: it must render a JSON object containing `external_id` plus at
+least one updatable action-log field — one of `status`, `sent_at`, or
+`metadata`. A minimal valid value:
+
+```liquid
+{"external_id": "{{ notification.messageId }}", "status": "delivered"}
+```
+
+Two distinct rejections come off this field, and they read differently:
+
+- **Missing entirely** — omitting `action_log_config` on create or
+  update is a 422 with `Missing field: action_log_config` at
+  `source.pointer: /action_log_config`.
+- **Present but renders nothing** — a value that passes shallow
+  validation but renders `null` or an empty result at run time (e.g.
+  a `{"type": "null"}` config) is refused with a 422 whose detail
+  begins `must render a JSON object containing external_id`.
+
+**Response nullability is lazy, not retroactive.** Updaters created
+before this became required still read back `action_log_config: null`
+— the platform does not backfill a template onto old rows. That
+`null` persists until the row's **next edit** forces a real template
+through, and "next edit" is broader than a plain field change: it
+also includes resuming a halted updater by setting `status` back to
+`'active'` (§7) and issuing a `refresh()` call with a one-shot
+`updater_body` override (§7) — both now require `action_log_config`
+to be present too, which is what completes the migration for an old
+row.
+
 ### `cron_expression` is a standard 5-field cron string
 
 ```
@@ -201,6 +389,7 @@ sender_tool_ids       required UUID[] — tools whose messages this updater trac
 datalake_id           required UUID
 updater_body          required embed  — { updater_body_type, ... }
 message_config        required embed  — { type, body }
+action_log_config     required embed  — { type, body } (required on create AND update)
 ```
 
 **Write-only (Request-only).** None.
@@ -216,6 +405,8 @@ Standard JSON:API envelopes per `errors.md`. Common rejections:
 | `/sender_tool_ids/0`                | tool id doesn't exist or wrong datalake            |
 | `/updater_body/updater_body_type`   | value not in the polymorphic embed's type enum     |
 | `/message_config/body`              | empty when `type: 'custom'`                        |
+| `/action_log_config`                | missing entirely — `Missing field: action_log_config` (create AND update) |
+| (detail, not pointer)               | `action_log_config` present but renders `null`/empty — detail begins `must render a JSON object containing external_id` |
 | `/base`                             | `cron_management_failed` — body validated and saved but scheduler registration failed; the row is rolled back |
 
 ## 5. Lifecycle
@@ -318,7 +509,7 @@ check or retry for partial-delete states.
    The poll follows pages while `has_next` is true and stops on
    the first empty page.
 
-## 7. Manual trigger via `refresh` — but still no per-run log
+## 7. Manual trigger via `refresh` — 202, and what `last_run_*` means
 
 An action status updater CAN be fired on demand:
 
@@ -328,28 +519,85 @@ const { data } = await api.actionStatusUpdaters.refresh(
 );
 ```
 
-`refresh` runs one poll cycle synchronously and returns the updater
-row with its `last_run_*` fields freshly stamped. Apply jobs are
-asynchronous — observe delivery status on the message rows, not in
-this response. (CLI: `alvera refresh-updater <id>`.)
+**`refresh` answers `202` with the updater row AS-IS — the poll is
+ENQUEUED, not run.** The `last_run_*` fields on that response are the
+PREVIOUS run's stamps; reading them as the outcome of the refresh you
+just issued is the single most common mistake here. An optional body
+carries a one-shot `updater_body` override (e.g. a widened
+`start_time`/`end_time` window for a backfill) that does not mutate
+the persisted updater. Apply jobs are asynchronous too — observe
+delivery status on the message rows, not in this response.
+(CLI: `alvera refresh-action-status-updater --id <uuid>`, alias
+`refresh-updater`.)
+
+The correct read is baseline-then-advance:
+
+```ts
+const before = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, updaterId)
+const baseline = before.data.last_run_at ?? null      // BEFORE refreshing
+
+await api.actionStatusUpdaters.refresh(tenantSlug, datalakeSlug, updaterId)
+
+let row = before.data
+const deadline = Date.now() + 60_000
+while (Date.now() < deadline) {
+  await new Promise((r) => setTimeout(r, 2_000))
+  const { data } = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, updaterId)
+  if (data.last_run_at && data.last_run_at !== baseline) { row = data; break }
+}
+// row.last_run_status / last_run_error now describe THIS run
+```
 
 What the ASU still does NOT have is a **per-run log** (nothing like
 a data activation client's `logs` or a workflow's `batchLogs`). The
-only run-outcome surface is four fields on the row itself,
-describing the most recent poll only:
+run-outcome surface is four fields on the row itself, plus the halt
+flag:
 
 ```
-last_run_at            when the poll worker last completed a run
-last_run_status        'ok' | 'error'
-last_run_error         why the last run failed (structured text)
-last_run_events_found  how many events that run fetched
+last_run_at            when the poll worker last made progress
+last_run_status        'ok' | 'partial' | 'error'
+last_run_error         why the last run failed, or why a partial run was truncated
+last_run_events_found  events fetched so far in the current run
+status                 'active' | 'cycle_detected'
 ```
 
+**A poll run has three outcomes, and only `'ok'` means it reconciled its
+whole time window:**
+
+- `'ok'` — the run completed and read its entire window. This is the only
+  value that proves the reconciliation is complete.
+- `'partial'` — the run completed but its provider fetch was **truncated**:
+  the window was not fully read, and the events it missed are the **newest**
+  ones. `last_run_error` carries the detail (it is **not** null on a
+  `partial` run). A client that treats `last_run_status !== 'error'` as
+  healthy silently accepts this incomplete reconciliation — check
+  `last_run_status === 'ok'` instead.
+- `'error'` — the run failed; `last_run_error` says why.
+
+`last_run_events_found` is the event count for the current run; because
+`refresh` is asynchronous (below), a read taken before the run finishes can
+legitimately show a smaller, in-progress figure than the final count.
+
+**`status` is the halt flag.** The server sets `'cycle_detected'` when
+a run re-reads events it has already handled — the runtime backstop for
+a poll whose pagination does not advance (a provider cursor that never
+drains, or a one-shot `updater_body` override). Every later job then
+fails without calling the provider, and `last_run_error` carries the
+diagnostic. **Nothing clears it but setting `status` back to
+`'active'`.** It is also the cheapest deterministic failure to assert
+on: a non-advancing config trips it within seconds, no provider
+credential rejection required. Related: a `restapi` updater that
+declares pagination but whose `path`/`params`/`body` never read
+`msg.pagination_context` or `msg.page` is now refused at create/update
+— see §2's template contract.
+
 **If a message's status is not reconciling, do this — in order:**
 
-1. Call `refresh()` and read `last_run_status` / `last_run_error`
-   off the response. They name the failing stage: window render,
-   source fetch, template render, or JSON parse.
+1. Call `refresh()`, wait for `last_run_at` to advance past the
+   baseline you captured, then read `last_run_status` /
+   `last_run_error` / `status`. They name the failing stage: window
+   render, source fetch, template render, JSON parse — or a halted
+   poll cycle.
 2. Check the config against §2 above. A config that violates the
    template contract is rejected at create, so a *deployed* updater's
    templates are structurally sound — the fault is more likely the

package/.agent/ai_sandbox.md

@@ -103,10 +103,12 @@ consumers cannot extend the set:
 
    minutes_ago   Unix ms N minutes before a unix-ms input. Bounds
                  the start of an ActionStatusUpdater poll window.
-                 Example:  {{ now | minutes_ago: 45 }}  →  1773585000000
+                 `now_msec` is the injected unix-ms variable (the
+                 bare `now` is a DateTime — feeding it here raises).
+                 Example:  {{ now_msec | minutes_ago: 45 }}  →  1773585000000
 
    hours_ago     Unix ms N hours before a unix-ms input.
-                 Example:  {{ now | hours_ago: 2 }}  →  1773578400000
+                 Example:  {{ now_msec | hours_ago: 2 }}  →  1773578400000
 
    uuid          Generate a new v4 UUID.
                  Example:  {{ '' | uuid }}  →  a1b2c3d4-…

package/.agent/connected_apps.md

@@ -64,7 +64,8 @@ const { data: created } = await api.connectedApps.create(
 )
 // created.id, created.slug         — server-derived
 // created.status                   === 'pending' (transient) → 'synced' after route fetch
-// created.api_key_id               — auto-provisioned M2M key id (see §2)
+// (an M2M key IS auto-provisioned at create (see §2), but its id is NOT
+//  echoed on the resource — no response carries an api_key_id field)
 // created.routes                   — array populated from .well-known/routes.json
 //                                     (empty until first sync)
 // created.last_synced_at           — set when routes successfully validated
@@ -191,9 +192,13 @@ last_synced_at    string — ISO 8601; set at successful route sync
 error             string — populated when status === 'error'
 routes            array  — discovered from .well-known/routes.json
                             (each: { name, path, description? })
-api_key_id        UUID   — id of the auto-provisioned M2M key
 ```
 
+(The auto-provisioned M2M key's id is **not** among these — neither
+`.get` nor `get-metadata` returns an `api_key_id`. Don't assert on it
+in a contract hook; the key itself reaches the deployment as
+`ALVERA_API_KEY`, §2.)
+
 **Caller-supplied (round-trip).**
 
 ```

package/.agent/cookbook/action-status-updaters.md

@@ -105,11 +105,16 @@ ctx.cwToolId = cwTool.id!
 
 The ASU ties it together: a `cron_expression` schedule, the `updater_tool_id`
 (the poller), the `sender_tool_ids` it reconciles for, and an `updater_body`
-naming the log group + the time window. On `start_time`/`end_time`, `now` is a
-variable holding unix milliseconds — pipe it through `minutes_ago`. The
+naming the log group + the time window. On `start_time`/`end_time`, use
+`now_msec` — the injected variable holding unix milliseconds — piped through
+`minutes_ago`; the bare `now` is a DateTime and raises here. The
 `message_config` Liquid is rendered ONCE PER EVENT, with the event itself as the
 assigns (there is no `events` list to loop), and emits a FLAT object: the
 `external_id` of the message to update plus the fields to set at the top level.
+`action_log_config` is REQUIRED alongside it — same per-event assigns, rendered
+into the action-log write shape: a JSON object with `external_id` plus at least
+one of `status` / `sent_at` / `metadata`. Omitting it is a 422 (`Missing field:
+action_log_config`).
 
 ```typescript
 const { data: asu } = await api.actionStatusUpdaters.create(tenantSlug, datalakeSlug, {
@@ -122,13 +127,17 @@ const { data: asu } = await api.actionStatusUpdaters.create(tenantSlug, datalake
   updater_body: {
     updater_body_type: 'cloud_watch_request',
     log_group_name: 'sns/us-east-1/000000000000/DirectPublishToPhoneNumber',
-    start_time: '{{ now | minutes_ago: 45 }}',
-    end_time: '{{ now }}',
+    start_time: '{{ now_msec | minutes_ago: 45 }}',
+    end_time: '{{ now_msec }}',
   },
   message_config: {
     type: 'custom',
     body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
   },
+  action_log_config: {
+    type: 'custom',
+    body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
+  },
 })
 actionStatusUpdaterId = asu.id!
 ```
@@ -155,13 +164,17 @@ const { data: ck } = await api.actionStatusUpdaters.checksum(tenantSlug, datalak
   updater_body: {
     updater_body_type: 'cloud_watch_request',
     log_group_name: 'sns/us-east-1/000000000000/DirectPublishToPhoneNumber',
-    start_time: '{{ now | minutes_ago: 45 }}',
-    end_time: '{{ now }}',
+    start_time: '{{ now_msec | minutes_ago: 45 }}',
+    end_time: '{{ now_msec }}',
   },
   message_config: {
     type: 'custom',
     body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
   },
+  action_log_config: {
+    type: 'custom',
+    body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
+  },
 })
 if (typeof ck.checksum !== 'string' || ck.checksum.length === 0) {
   throw new Error('expected a checksum for the ASU body')
@@ -190,6 +203,35 @@ if (typeof detail !== 'string' || detail.length === 0) {
 }
 ```
 
+## 007 — write the integration test
+
+End the build with a test you keep: one block that re-reads the reconciler
+and asserts the facts the scenario depends on. This block runs live under
+`make validate-cookbook`.
+
+```typescript
+// Re-GET — the stored row echoes what was authored.
+const { data: asuRow } = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, actionStatusUpdaterId)
+if (asuRow.cron_expression !== '*/30 * * * *') {
+  throw new Error(`cron mismatch on read-back: ${asuRow.cron_expression}`)
+}
+// last_run_* is the ONLY run surface (there is no per-run log). On a
+// fresh create it is legitimately null — assert the field EXISTS on the
+// wire, never a value.
+if (!('last_run_status' in asuRow)) {
+  throw new Error('ASU response carries no last_run_status field')
+}
+// Behavioural probe — the metadata surface an agent reads must render.
+const { data: asuDetail } = await api.actionStatusUpdaters.metadataDetails(tenantSlug, datalakeSlug, actionStatusUpdaterId)
+if (typeof asuDetail !== 'string' || asuDetail.length === 0) {
+  throw new Error('ASU metadataDetails came back empty')
+}
+```
+
+If the test fails in production, escalate with the failing read's
+evidence (the response body, `last_run_error`) — don't rewrite the config
+blind.
+
 # Gotchas
 
 - **The poller tool's intent is `status_poller`, not the sender's intent.** The
@@ -199,14 +241,31 @@ if (typeof detail !== 'string' || detail.length === 0) {
   is the assigns — there is no `events` list to loop — and every top-level key
   that is not `external_id` IS the update (`status`, `delivered_at`, …). There is
   no `set_params` wrapper. Both mistakes are rejected at create.
-- **The schedule is a cron, evaluated platform-side, and you CANNOT trigger it.**
-  Creating the ASU registers the schedule. The `updater_body` window
-  (`{{ now | minutes_ago: 45 }}` … `{{ now }}`) bounds each run's log query, and
-  must render to unix milliseconds — `now` is a variable here, not the ISO-8601
-  `now` filter.
-- **If it doesn't reconcile, read `last_run_error` and then ESCALATE.** There is
-  no manual trigger and no per-run log (known limitation). Don't rewrite the
-  config and wait for another cron tick — see `action_status_updaters.md` §7.
+- **`action_log_config` is REQUIRED on both create and update (PUT), same as
+  `message_config`.** Omitting it is a 422 (`Missing field: action_log_config`).
+  It renders the same per-event assigns into the action-log write shape:
+  `external_id` plus at least one of `status` / `sent_at` / `metadata`.
+- **The schedule is a cron, evaluated platform-side — and one poll cycle can
+  be fired on demand.** Creating the ASU registers the schedule. The
+  `updater_body` window (`{{ now_msec | minutes_ago: 45 }}` … `{{ now_msec }}`)
+  bounds each run's log query, and must render to unix milliseconds — `now_msec`
+  is the unix-ms variable, not the bare `now` (a DateTime) or the ISO-8601 `now`
+  filter. To trigger a cycle without
+  waiting for the cron tick, `api.actionStatusUpdaters.refresh(tenantSlug,
+  datalakeSlug, id)` answers `202` with the updater row AS-IS (the poll runs
+  async — the row still shows the PREVIOUS run's stamps; re-read later for
+  the outcome). See `action_status_updaters.md` §7.
+- **If it doesn't reconcile, read `last_run_error` — refresh, don't guess.**
+  There is no per-run log (known limitation): the run surface is the
+  read-only `last_run_*` fields. Fire a `refresh`, re-read `last_run_status`
+  / `last_run_events_found` / `last_run_error`, and escalate with that
+  evidence — don't rewrite the config blind between cron ticks.
+- **`last_run_status` has three values — only `'ok'` means done.** `'ok'`
+  is the run that read its whole time window; `'partial'` completed but its
+  provider fetch was truncated, so the newest events may be missing and
+  `last_run_error` says so (it is not null on a `partial`); `'error'` failed.
+  Check `last_run_status === 'ok'` — a `!== 'error'` check silently accepts
+  a truncated `partial` as if it had reconciled.
 - **`checksum` parity is your drift signal.** The fingerprint of the desired body
   must match the stored row's; a mismatch means the resource drifted.
 

package/.agent/cookbook/ai-agent-invoke.md

@@ -214,6 +214,42 @@ if (!rejected) {
 }
 ```
 
+## 006 — write the integration test
+
+End the build with a test you keep: re-read the agent and probe the one
+behaviour that is provable deterministically — the input gate. A real
+extraction (§004) needs a live provider behind the tool; the schema gate
+does not, which is exactly what makes it the durable test. This block
+runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the agent must be enabled, or every invoke will refuse.
+const { data: agentRow } = await api.aiAgents.get(tenantSlug, datalakeSlug, aiAgentId)
+if (agentRow.enabled !== true) {
+  throw new Error('expected enabled=true on agent read-back')
+}
+// Behavioural probe — the input_schema gate fires BEFORE the model:
+// a malformed input must 422 even with no working provider.
+let gateFired = false
+try {
+  await api.aiAgents.invoke(tenantSlug, datalakeSlug, aiAgentId, {
+    input: { wrong_field: 'test — no instructions here' },
+    files: [],
+  })
+} catch (err) {
+  const status = (err as { _httpStatus?: number })._httpStatus
+  if (status !== 422) throw err
+  gateFired = true
+}
+if (!gateFired) {
+  throw new Error('agent accepted input that violates its input_schema (expected 422)')
+}
+```
+
+If the gate stops firing in production, escalate with the
+accepted-payload evidence — don't loosen the `input_schema` to make the
+error go away.
+
 # Gotchas
 
 - **Uploading a file is not ingesting it.** The upload + `invoke` here makes the