@alvera-ai/platform-sdk 0.17.3 → 0.17.4-next.g6daa781

package/.agent/action_status_updaters.md

@@ -14,8 +14,8 @@ polls the provider's log group to mark each message as
 SDK namespace: `api.actionStatusUpdaters`.
 
 Action status updaters are **Datalake-DB-resident** — the
-parent datalake must be `status: 'ready'` and every
-referenced tool must exist before you `create()`.
+parent datalake must be `status: 'ready'`, and the polling tool
+and the data source must exist before you `create()`.
 
 ## 1. Wire shape
 
@@ -33,7 +33,7 @@ const { data: created } = await api.actionStatusUpdaters.create(
     cron_expression: '*/30 * * * *',                  // every 30 minutes
     updater_type: 'cloud_watch',                      // polling source family
     updater_tool_id: cloudWatchToolId,                // the tool that issues the poll
-    sender_tool_ids: [smsToolId],                     // tools whose sent messages this updater tracks
+    data_source_id: dataSourceId,                     // the data source whose messages + action logs this updater updates
     datalake_id: datalakeId,
 
     // Polymorphic — discriminator: updater_body_type
@@ -354,7 +354,7 @@ anyway — a future release may start enforcing it, and a lying
 `updater_type` is a debugging trap — but don't expect a 422 to catch
 a mismatch for you today.
 
-### `updater_tool_id` and `sender_tool_ids` serve different roles
+### `updater_tool_id` and `data_source_id` serve different roles
 
 - `updater_tool_id` (single) — the tool the updater uses to
   ISSUE the poll. By convention this is a tool whose `intent` is
@@ -364,14 +364,25 @@ a mismatch for you today.
   wrong-intent tool is accepted and only fails later, when the poll
   actually runs. Wire a `status_poller` tool anyway; just don't rely
   on a create-time 422 to enforce it.
-- `sender_tool_ids` (array) — the tools whose sent messages
-  this updater is responsible for tracking. The match logic
-  joins each polled event back to a message row that was
-  sent through one of these tools.
-
-A single status updater can track messages from multiple
-sender tools (e.g. an SMS tool plus a voice tool routed
-through the same provider).
+- `data_source_id` (single) — the data source whose messages and
+  action logs this updater updates. Every tool names a data source
+  (`tools.md`), and every message a tool sends carries that data
+  source's `uri`. The updater matches each polled event to a row by
+  the data source's `uri` plus the vendor's id (`external_id`): the
+  unique key on messages and action logs is
+  `(data_source_uri, external_id)`, and a vendor id that repeats
+  under one data source is kept with status `duplicate`.
+
+So the updater is not tied to one sender tool: a message sent
+through any tool on its data source is a candidate for its match.
+One data source may hold SMS, MMS and voice tools, and nothing
+checks what else is on it.
+
+`data_source_id` is required on create AND update (PUT replaces the
+whole body). The response reads it back nullable: updaters created
+before it existed carry none, skip every run, and report
+`no data source: …` as their last run error until an update names
+one.
 
 ## 3. Field ownership
 
@@ -385,7 +396,7 @@ name                  required string
 cron_expression       required string — standard cron
 updater_type          required enum   — e.g. 'cloud_watch'
 updater_tool_id       required UUID   — the polling tool
-sender_tool_ids       required UUID[] — tools whose messages this updater tracks
+data_source_id        required UUID   — the data source whose messages + action logs this updater updates (read back nullable)
 datalake_id           required UUID
 updater_body          required embed  — { updater_body_type, ... }
 message_config        required embed  — { type, body }
@@ -402,7 +413,7 @@ Standard JSON:API envelopes per `errors.md`. Common rejections:
 |-------------------------------------|----------------------------------------------------|
 | `/cron_expression`                  | invalid cron syntax or below minimum interval      |
 | `/updater_tool_id`                  | tool id doesn't exist or wrong datalake (intent is NOT checked — see §2) |
-| `/sender_tool_ids/0`                | tool id doesn't exist or wrong datalake            |
+| `/data_source_id`                   | missing (`can't be blank`, create AND update) or the data source doesn't exist |
 | `/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) |
@@ -626,7 +637,7 @@ is the part that matters:
 - **No updater configured → no delivery truth.** Rows stay `sent`
   forever; a delivery-rate number computed from them is fiction.
   Updaters are created manually (this page §1) — the platform does
-  not auto-create them per sender tool.
+  not auto-create them per data source.
 - **The join is `{external_id, set_params}`,** exact-match, silent
   on misses (gotcha 3). "Eventually honest": a just-sent row is
   neither delivered nor failed yet — show the in-between state.

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

@@ -22,7 +22,8 @@ An **action status updater (ASU)** is a scheduled reconciler:
 - the ASU runs on a `cron_expression`,
 - its `message_config` Liquid maps each log event back to the message it came
   from (by `external_id`) and the new `status`,
-- `sender_tool_ids` scopes it to the messages a given sender tool produced.
+- `data_source_id` scopes it to one data source: the messages and action logs
+  that carry that data source's `uri` — every message a tool on it sends.
 
 This is **global** — the same shape reconciles any sender's delivery status. See
 `action_status_updaters.md` for the wire reference and `tools.md` for the
@@ -104,7 +105,8 @@ ctx.cwToolId = cwTool.id!
 ## 004 — create the action status updater
 
 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`
+(the poller), the `data_source_id` whose messages it reconciles — the one the
+SMS sender tool names — and an `updater_body`
 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
@@ -122,7 +124,7 @@ const { data: asu } = await api.actionStatusUpdaters.create(tenantSlug, datalake
   cron_expression: '*/30 * * * *',
   updater_type: 'cloud_watch',
   updater_tool_id: ctx.cwToolId,
-  sender_tool_ids: [ctx.smsToolId],
+  data_source_id: dataSourceId,
   datalake_id: ctx.datalakeId,
   updater_body: {
     updater_body_type: 'cloud_watch_request',
@@ -159,7 +161,7 @@ const { data: ck } = await api.actionStatusUpdaters.checksum(tenantSlug, datalak
   cron_expression: row.cron_expression,
   updater_type: 'cloud_watch',
   updater_tool_id: ctx.cwToolId,
-  sender_tool_ids: [ctx.smsToolId],
+  data_source_id: dataSourceId,
   datalake_id: ctx.datalakeId,
   updater_body: {
     updater_body_type: 'cloud_watch_request',
@@ -235,8 +237,9 @@ blind.
 # Gotchas
 
 - **The poller tool's intent is `status_poller`, not the sender's intent.** The
-  reconciler reads logs; it doesn't send. `sender_tool_ids` is the separate list
-  of sender tools whose messages it updates.
+  reconciler reads logs; it doesn't send. The messages it updates are named by
+  `data_source_id`, not by a list of sender tools: every tool names a data
+  source, and the messages it sends carry that data source's `uri`.
 - **`message_config` renders once per event, and emits a FLAT object.** The event
   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

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

@@ -99,12 +99,22 @@ const OPENAI_BASE_BODY =
 const OPENAI_EXTRACTOR =
   '{"output_json": "{{ msg.choices[0].message.content | json_escape }}", "explanation": "{{ msg.choices[0].message.reasoning_content | json_escape }}", "input_tokens": {{ msg.usage.prompt_tokens | default: 0 }}, "output_tokens": {{ msg.usage.completion_tokens | default: 0 }}, "total_tokens": {{ msg.usage.total_tokens | default: 0 }}}'
 
+// Every tool names a data source; this one exists for the LLM tool alone.
+const { data: toolSource } = await api.dataSources.create(tenantSlug, datalakeSlug, {
+  name: `Extraction Tool Source ${runSuffix}`,
+  uri: 'openai.local',
+  description: 'Data source the LLM-enrichment tool names.',
+  status: 'active',
+  is_default: false,
+})
+
 const { data: tool } = await api.tools.create(tenantSlug, datalakeSlug, {
   name: `Legal-Entity Extraction Tool ${runSuffix}`,
   description: 'Multimodal LLM-enrichment adapter for legal_entity extraction.',
   intent: 'llm_enrichment',
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: toolSource.id!,
   response_extractor: { type: 'custom', body: OPENAI_EXTRACTOR, output_schema: ENRICHMENT_OUTPUT_SCHEMA },
   body: {
     tool_body_type: 'rest_api',

package/.agent/cookbook/appointment-review-sms-workflow.md

@@ -77,13 +77,27 @@ dev points it at LocalStack on `http://localhost:4566` via
 `intent: 'sms'` tags this tool for workflow actions that send SMS
 (versus `data_exchange` for ingestion tools).
 
+Every tool names a data source, and the messages a sender tool sends carry
+that data source's `uri` — what a status updater matches on — so the step
+creates one for the SMS tool first.
+
 ```typescript
+const toolSourceResp = await api.dataSources.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SMS Source ${runSuffix}`,
+  uri: 'sns.local',
+  description: 'Origin of the messages the SMS tool sends.',
+  status: 'active',
+  is_default: false,
+})
+ctx.toolSourceId = toolSourceResp.data.id!
+
 const smsToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
   name: `Cookbook SMS Tool ${runSuffix}`,
   description: 'SNS-backed SMS dispatcher for the Review SMS workflow, wired to LocalStack.',
   intent: 'sms',
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: ctx.toolSourceId,
   body: {
     tool_body_type: 'sns',
     auth_method: 'access_key',

package/.agent/cookbook/birthday-greeting-sms-trigger.md

@@ -70,13 +70,27 @@ local dev points it at LocalStack on `http://localhost:4566` via
 `intent: 'sms'` tags this tool for workflow actions that send SMS
 (versus `data_exchange` for ingestion tools).
 
+Every tool names a data source, and the messages a sender tool sends carry
+that data source's `uri` — what a status updater matches on — so the step
+creates one for the SMS tool first.
+
 ```typescript
+const toolSourceResp = await api.dataSources.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SMS Source ${runSuffix}`,
+  uri: 'sns.local',
+  description: 'Origin of the messages the SMS tool sends.',
+  status: 'active',
+  is_default: false,
+})
+ctx.toolSourceId = toolSourceResp.data.id!
+
 const smsToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
   name: `Cookbook SMS Tool ${runSuffix}`,
   description: 'SNS-backed SMS dispatcher for the Happy Birthday workflow, wired to LocalStack.',
   intent: 'sms',
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: ctx.toolSourceId,
   body: {
     tool_body_type: 'sns',
     auth_method: 'access_key',

package/.agent/cookbook/contact-us-triage-with-llm.md

@@ -136,13 +136,27 @@ per-bucket SMS body lives on each workflow action, not on the tool.
 SNS-backed LocalStack wiring — `intent: 'sms'` tags it for
 workflow-action use.
 
+Every tool names a data source, and the messages a sender tool sends carry
+that data source's `uri` — what a status updater matches on — so the step
+creates one for the SMS tool first.
+
 ```typescript
+const toolSourceResp = await api.dataSources.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SMS Source ${runSuffix}`,
+  uri: 'sns.local',
+  description: 'Origin of the messages the SMS tool sends.',
+  status: 'active',
+  is_default: false,
+})
+ctx.toolSourceId = toolSourceResp.data.id!
+
 const smsToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
   name: `Cookbook SMS Tool ${runSuffix}`,
   description: 'SNS-backed SMS dispatcher for the Contact Us Triage workflow, wired to LocalStack.',
   intent: 'sms',
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: ctx.toolSourceId,
   body: {
     tool_body_type: 'sns',
     auth_method: 'access_key',
@@ -194,6 +208,7 @@ const llmToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
   intent: 'llm_enrichment',
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: ctx.toolSourceId,
   response_extractor: { type: 'custom', body: OLLAMA_EXTRACTOR, output_schema: ENRICHMENT_OUTPUT_SCHEMA },
   body: {
     tool_body_type: 'rest_api',

package/.agent/cookbook/dunning-sms-for-delinquent.md

@@ -79,13 +79,27 @@ dev points it at LocalStack on `http://localhost:4566` via
 `intent: 'sms'` tags this tool for workflow actions that send SMS
 (versus `data_exchange` for ingestion tools).
 
+Every tool names a data source, and the messages a sender tool sends carry
+that data source's `uri` — what a status updater matches on — so the step
+creates one for the SMS tool first.
+
 ```typescript
+const toolSourceResp = await api.dataSources.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SMS Source ${runSuffix}`,
+  uri: 'sns.local',
+  description: 'Origin of the messages the SMS tool sends.',
+  status: 'active',
+  is_default: false,
+})
+ctx.toolSourceId = toolSourceResp.data.id!
+
 const smsToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
   name: `Cookbook SMS Tool ${runSuffix}`,
   description: 'SNS-backed SMS dispatcher for the Dunning SMS workflow, wired to LocalStack.',
   intent: 'sms',
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: ctx.toolSourceId,
   body: {
     tool_body_type: 'sns',
     auth_method: 'access_key',

package/.agent/cookbook/kyc-notification-on-account-activation.md

@@ -77,13 +77,27 @@ local dev points it at LocalStack on `http://localhost:4566` via
 `intent: 'sms'` tags this tool for workflow actions that send SMS
 (versus `data_exchange` for ingestion tools).
 
+Every tool names a data source, and the messages a sender tool sends carry
+that data source's `uri` — what a status updater matches on — so the step
+creates one for the SMS tool first.
+
 ```typescript
+const toolSourceResp = await api.dataSources.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SMS Source ${runSuffix}`,
+  uri: 'sns.local',
+  description: 'Origin of the messages the SMS tool sends.',
+  status: 'active',
+  is_default: false,
+})
+ctx.toolSourceId = toolSourceResp.data.id!
+
 const smsToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
   name: `Cookbook SMS Tool ${runSuffix}`,
   description: 'SNS-backed SMS dispatcher for the KYC-notification workflow, wired to LocalStack.',
   intent: 'sms',
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: ctx.toolSourceId,
   body: {
     tool_body_type: 'sns',
     auth_method: 'access_key',

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

@@ -507,6 +507,15 @@ manifest therefore runs against any server; you are not asking the
 deployment to be in "test mode". Swap `mock` for `ses` and the same
 workflow sends real email.
 
+The sender lives in the tool's Base Configuration: `base_from_email`
+(required on every email tool) and `base_from_name`, Liquid templates
+rendered when the tool is saved with the tool's own variables only
+(`tool.name`, `tool.provider`, …). An email action's own `from_email` /
+`from_name` / `reply_to` still win, field by field, when they render
+non-blank. Both tools name the campaign's data source, as every tool
+must; the messages they send carry its `uri`, which is what §009's
+status updater matches on.
+
 The connected app is the campaign's booking form. It is registered
 here, and §010's actions deep-link into it.
 
@@ -519,6 +528,7 @@ const { data: smsTool } = await api.tools.create(tenantSlug, datalakeSlug, {
   intent: ToolIntent.SMS,
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: dataSourceId,
   body: {
     tool_body_type: 'sns',
     auth_method: 'access_key',
@@ -537,11 +547,12 @@ const { data: emailTool } = await api.tools.create(tenantSlug, datalakeSlug, {
   intent: ToolIntent.EMAIL,
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: dataSourceId,
   body: {
     tool_body_type: 'email',
     provider: 'mock',
-    from_email: 'campaigns@bloom-salon.example.com',
-    from_name: 'Bloom Salon',
+    base_from_email: { type: 'custom', body: 'campaigns@bloom-salon.example.com' },
+    base_from_name: { type: 'custom', body: 'Bloom Salon' },
   },
 })
 ctx.emailToolId = emailTool.id!
@@ -652,11 +663,12 @@ const { data: sesTool } = await api.tools.create(tenantSlug, datalakeSlug, {
   intent: ToolIntent.EMAIL,
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: dataSourceId,
   body: {
     tool_body_type: 'email',
     provider: 'ses',
-    from_email: sesSender,
-    from_name: 'Bloom Salon',
+    base_from_email: { type: 'custom', body: sesSender },
+    base_from_name: { type: 'custom', body: 'Bloom Salon' },
     region: 'us-east-1',
     access_key_id: 'localkey',
     secret_access_key: 'localsecret',
@@ -748,7 +760,7 @@ const { data: sesUpdater } = await api.actionStatusUpdaters.create(tenantSlug, d
   cron_expression: '*/30 * * * *',
   updater_type: 'cloud_watch',
   updater_tool_id: sesReader.id!,
-  sender_tool_ids: [ctx.sesToolId],
+  data_source_id: dataSourceId,
   datalake_id: ctx.datalakeId,
   updater_body: {
     updater_body_type: 'cloud_watch_request',

package/.agent/cookbook/paginated-restapi-poller.md

@@ -57,8 +57,9 @@ dataSourceId = ds.id!
 
 ## 002 — create the sender tool whose messages get reconciled
 
-The ASU updates messages a sender produced; `sender_tool_ids` will point here.
-An SNS-backed SMS sender (LocalStack locally) plays that role.
+The ASU updates the messages sent through its data source; the sender names
+that data source, so its messages carry the data source's `uri`. An
+SNS-backed SMS sender (LocalStack locally) plays that role.
 
 ```typescript
 const { data: smsTool } = await api.tools.create(tenantSlug, datalakeSlug, {
@@ -126,7 +127,7 @@ try {
     cron_expression: '*/30 * * * *',
     updater_type: 'restapi',
     updater_tool_id: ctx.restToolId,
-    sender_tool_ids: [ctx.senderToolId],
+    data_source_id: dataSourceId,
     datalake_id: ctx.datalakeId,
     // FLOOR the platform enforces: an array whose items are objects listing
     // `external_id` in `required`. A bare `{ type: 'array' }` is a 422 at
@@ -201,7 +202,7 @@ const { data: asu } = await api.actionStatusUpdaters.create(tenantSlug, datalake
   cron_expression: '*/30 * * * *',
   updater_type: 'restapi',
   updater_tool_id: ctx.restToolId,
-  sender_tool_ids: [ctx.senderToolId],
+  data_source_id: dataSourceId,
   datalake_id: ctx.datalakeId,
   events_output_schema: {
     type: 'array',

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

@@ -82,13 +82,27 @@ local dev points it at LocalStack on `http://localhost:4566` via
 `intent: 'sms'` tags this tool for workflow actions that send SMS
 (versus `data_exchange` for ingestion tools).
 
+Every tool names a data source, and the messages a sender tool sends carry
+that data source's `uri` — what a status updater matches on — so the step
+creates one for the SMS tool first.
+
 ```typescript
+const toolSourceResp = await api.dataSources.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SMS Source ${runSuffix}`,
+  uri: 'sns.local',
+  description: 'Origin of the messages the SMS tool sends.',
+  status: 'active',
+  is_default: false,
+})
+ctx.toolSourceId = toolSourceResp.data.id!
+
 const smsToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
   name: `Cookbook SMS Tool ${runSuffix}`,
   description: 'SNS-backed SMS dispatcher for the Sanctions Review workflow, wired to LocalStack.',
   intent: 'sms',
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: ctx.toolSourceId,
   body: {
     tool_body_type: 'sns',
     auth_method: 'access_key',
@@ -141,6 +155,7 @@ const llmToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
   intent: 'llm_enrichment',
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: ctx.toolSourceId,
   response_extractor: { type: 'custom', body: OLLAMA_EXTRACTOR, output_schema: ENRICHMENT_OUTPUT_SCHEMA },
   body: {
     tool_body_type: 'rest_api',

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

@@ -146,13 +146,27 @@ per-band SMS body lives on each workflow action, not on the tool. Same
 SNS-backed LocalStack wiring as the birthday cookbook — `intent: 'sms'`
 tags it for workflow-action use.
 
+Every tool names a data source, and the messages a sender tool sends carry
+that data source's `uri` — what a status updater matches on — so the step
+creates one for the SMS tool first.
+
 ```typescript
+const toolSourceResp = await api.dataSources.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SMS Source ${runSuffix}`,
+  uri: 'sns.local',
+  description: 'Origin of the messages the SMS tool sends.',
+  status: 'active',
+  is_default: false,
+})
+ctx.toolSourceId = toolSourceResp.data.id!
+
 const smsToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
   name: `Cookbook SMS Tool ${runSuffix}`,
   description: 'SNS-backed SMS dispatcher for the Score Lead workflow, wired to LocalStack.',
   intent: 'sms',
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: ctx.toolSourceId,
   body: {
     tool_body_type: 'sns',
     auth_method: 'access_key',
@@ -204,6 +218,7 @@ const llmToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
   intent: 'llm_enrichment',
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: ctx.toolSourceId,
   response_extractor: { type: 'custom', body: OLLAMA_EXTRACTOR, output_schema: ENRICHMENT_OUTPUT_SCHEMA },
   body: {
     tool_body_type: 'rest_api',

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

@@ -65,13 +65,27 @@ A single SMS tool dispatches every band's message; the per-band body lives on
 each workflow action. SNS-backed, pointed at LocalStack locally; `intent: 'sms'`
 tags it for workflow actions.
 
+Every tool names a data source, and the messages a sender tool sends carry
+that data source's `uri` — what a status updater matches on — so the step
+creates one for the SMS tool first.
+
 ```typescript
+const toolSourceResp = await api.dataSources.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SMS Source ${runSuffix}`,
+  uri: 'sns.local',
+  description: 'Origin of the messages the SMS tool sends.',
+  status: 'active',
+  is_default: false,
+})
+ctx.toolSourceId = toolSourceResp.data.id!
+
 const smsToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
   name: `Cookbook SMS Tool ${runSuffix}`,
   description: 'SNS-backed SMS dispatcher for the priority-triage workflow, wired to LocalStack.',
   intent: 'sms',
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: ctx.toolSourceId,
   body: {
     tool_body_type: 'sns',
     auth_method: 'access_key',
@@ -119,6 +133,7 @@ const llmToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
   intent: 'llm_enrichment',
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: ctx.toolSourceId,
   response_extractor: { type: 'custom', body: OLLAMA_EXTRACTOR, output_schema: ENRICHMENT_OUTPUT_SCHEMA },
   body: {
     tool_body_type: 'rest_api',

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

@@ -76,13 +76,27 @@ dev points it at LocalStack on `http://localhost:4566` via
 `intent: 'sms'` tags this tool for workflow actions that send SMS
 (versus `data_exchange` for ingestion tools).
 
+Every tool names a data source, and the messages a sender tool sends carry
+that data source's `uri` — what a status updater matches on — so the step
+creates one for the SMS tool first.
+
 ```typescript
+const toolSourceResp = await api.dataSources.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SMS Source ${runSuffix}`,
+  uri: 'sns.local',
+  description: 'Origin of the messages the SMS tool sends.',
+  status: 'active',
+  is_default: false,
+})
+ctx.toolSourceId = toolSourceResp.data.id!
+
 const smsToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
   name: `Cookbook SMS Tool ${runSuffix}`,
   description: 'SNS-backed SMS dispatcher for the Welcome SMS workflow, wired to LocalStack.',
   intent: 'sms',
   status: 'active',
   datalake_id: ctx.datalakeId,
+  data_source_id: ctx.toolSourceId,
   body: {
     tool_body_type: 'sns',
     auth_method: 'access_key',

package/.agent/data_sources.md

@@ -210,6 +210,9 @@ asymmetric cascade behavior by dependent resource:
   restricting FK (`on_delete: :restrict`), so the delete is
   **rejected** while any action still points at the source —
   detach those actions first.
+- Every tool names its data source (`tools.md` §2), and that FK
+  restricts too: a data source that still has tools answers
+  `409` (`still has tools`). Delete or move its tools first.
 
 The auto-created default Manual Upload source (see §2 "A
 default Manual Upload data source is auto-created per

package/.agent/tool-call-configs.md

@@ -99,8 +99,10 @@ Sends an email message via the configured email provider.
 - **to** (TemplateConfig) — Recipient email address (RFC 5322), rendered as Liquid template
 - **subject** (TemplateConfig) — Email subject line, rendered as Liquid template
 - **body** (TemplateConfig) — Email body, rendered as Liquid template
-- **from_name** (TemplateConfig, optional) — Sender display name; overrides the email tool's `from_name`
-- **from_email** (TemplateConfig, optional) — Sender address (RFC 5322); overrides the email tool's `from_email`
-- **reply_to** (TemplateConfig, optional) — Reply-to address (RFC 5322); overrides the email tool's `reply_to`
+- **from_name** (TemplateConfig, optional) — Sender display name; overrides the email tool's `base_from_name`
+- **from_email** (TemplateConfig, optional) — Sender address (RFC 5322); overrides the email tool's `base_from_email`
+- **reply_to** (TemplateConfig, optional) — Reply-to address (RFC 5322); overrides the email tool's `base_reply_to`
 
-Each optional sender field the action leaves unset, or that renders blank, keeps the email tool's value.
+The email tool's Base Configuration renders first. Each field the action leaves unset, or that renders blank,
+keeps the tool's value — the sender fields, and `to`, `subject` and `body` against `base_to`, `base_subject`
+and `base_body`.