@alvera-ai/platform-sdk 0.17.4-next.gc508af1 → 0.17.4

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 the polling tool
-and the data source must exist before you `create()`.
+parent datalake must be `status: 'ready'` and every
+referenced tool 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
-    data_source_id: dataSourceId,                     // the data source whose messages + action logs this updater updates
+    sender_tool_ids: [smsToolId],                     // tools whose sent messages this updater tracks
     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 `data_source_id` serve different roles
+### `updater_tool_id` and `sender_tool_ids` 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,25 +364,14 @@ 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.
-- `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.
+- `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).
 
 ## 3. Field ownership
 
@@ -396,7 +385,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
-data_source_id        required UUID   — the data source whose messages + action logs this updater updates (read back nullable)
+sender_tool_ids       required UUID[] — tools whose messages this updater tracks
 datalake_id           required UUID
 updater_body          required embed  — { updater_body_type, ... }
 message_config        required embed  — { type, body }
@@ -413,7 +402,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) |
-| `/data_source_id`                   | missing (`can't be blank`, create AND update) or the data source doesn't exist |
+| `/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) |
@@ -637,7 +626,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 data source.
+  not auto-create them per sender tool.
 - **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,8 +22,7 @@ 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`,
-- `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.
+- `sender_tool_ids` scopes it to the messages a given sender tool produced.
 
 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
@@ -105,8 +104,7 @@ 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 `data_source_id` whose messages it reconciles — the one the
-SMS sender tool names — and an `updater_body`
+(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`, use
 `now_msec` — the injected variable holding unix milliseconds — piped through
 `minutes_ago`; the bare `now` is a DateTime and raises here. The
@@ -124,7 +122,7 @@ const { data: asu } = await api.actionStatusUpdaters.create(tenantSlug, datalake
   cron_expression: '*/30 * * * *',
   updater_type: 'cloud_watch',
   updater_tool_id: ctx.cwToolId,
-  data_source_id: dataSourceId,
+  sender_tool_ids: [ctx.smsToolId],
   datalake_id: ctx.datalakeId,
   updater_body: {
     updater_body_type: 'cloud_watch_request',
@@ -161,7 +159,7 @@ const { data: ck } = await api.actionStatusUpdaters.checksum(tenantSlug, datalak
   cron_expression: row.cron_expression,
   updater_type: 'cloud_watch',
   updater_tool_id: ctx.cwToolId,
-  data_source_id: dataSourceId,
+  sender_tool_ids: [ctx.smsToolId],
   datalake_id: ctx.datalakeId,
   updater_body: {
     updater_body_type: 'cloud_watch_request',
@@ -237,9 +235,8 @@ blind.
 # Gotchas
 
 - **The poller tool's intent is `status_poller`, not the sender's intent.** The
-  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`.
+  reconciler reads logs; it doesn't send. `sender_tool_ids` is the separate list
+  of sender tools whose messages it updates.
 - **`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,22 +99,12 @@ 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,27 +77,13 @@ 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,27 +70,13 @@ 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,27 +136,13 @@ 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',
@@ -208,7 +194,6 @@ 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,27 +79,13 @@ 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,27 +77,13 @@ 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

@@ -512,9 +512,7 @@ The sender lives in the tool's Base Configuration: `base_from_email`
 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.
+non-blank.
 
 The connected app is the campaign's booking form. It is registered
 here, and §010's actions deep-link into it.
@@ -528,7 +526,6 @@ 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',
@@ -547,7 +544,6 @@ 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',
@@ -663,7 +659,6 @@ 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',
@@ -760,7 +755,7 @@ const { data: sesUpdater } = await api.actionStatusUpdaters.create(tenantSlug, d
   cron_expression: '*/30 * * * *',
   updater_type: 'cloud_watch',
   updater_tool_id: sesReader.id!,
-  data_source_id: dataSourceId,
+  sender_tool_ids: [ctx.sesToolId],
   datalake_id: ctx.datalakeId,
   updater_body: {
     updater_body_type: 'cloud_watch_request',

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

@@ -57,9 +57,8 @@ dataSourceId = ds.id!
 
 ## 002 — create the sender tool whose messages get reconciled
 
-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.
+The ASU updates messages a sender produced; `sender_tool_ids` will point here.
+An SNS-backed SMS sender (LocalStack locally) plays that role.
 
 ```typescript
 const { data: smsTool } = await api.tools.create(tenantSlug, datalakeSlug, {
@@ -127,7 +126,7 @@ try {
     cron_expression: '*/30 * * * *',
     updater_type: 'restapi',
     updater_tool_id: ctx.restToolId,
-    data_source_id: dataSourceId,
+    sender_tool_ids: [ctx.senderToolId],
     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
@@ -202,7 +201,7 @@ const { data: asu } = await api.actionStatusUpdaters.create(tenantSlug, datalake
   cron_expression: '*/30 * * * *',
   updater_type: 'restapi',
   updater_tool_id: ctx.restToolId,
-  data_source_id: dataSourceId,
+  sender_tool_ids: [ctx.senderToolId],
   datalake_id: ctx.datalakeId,
   events_output_schema: {
     type: 'array',

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

@@ -82,27 +82,13 @@ 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',
@@ -155,7 +141,6 @@ 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,27 +146,13 @@ 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',
@@ -218,7 +204,6 @@ 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,27 +65,13 @@ 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',
@@ -133,7 +119,6 @@ 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,27 +76,13 @@ 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,9 +210,6 @@ 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/tools.md

@@ -12,11 +12,10 @@ dimensions:
 - **body type** declares HOW the tool connects (S3, SFTP, SQL,
   REST, AWS Lambda, …) via a polymorphic discriminator
 
-A datalake can own many tools, and every tool names the data source
-it belongs to (`data_source_id`, required on every intent — see §2).
-A tool stays reachable to any workflow on the datalake; the data
-source decides which `uri` the messages it sends carry, which is what
-action status updaters match on.
+A datalake can own many tools. Some tools nest under a data source
+(`data_source_id` populated — typical for ingestion-receiving
+tools like `manual_upload`); others are standalone and reachable
+to any workflow on the datalake.
 
 ## 1. Wire shape
 
@@ -120,7 +119,6 @@ happened to it** — no delivery status, no reconciliation.
 await api.tools.create(tenantSlug, datalakeSlug, {
   name: 'Campaign Sender — Main Line',
   intent: 'sms',
-  data_source_id: dataSourceId,  // every tool names one; its messages carry this source's uri
   tool_body_type: 'twilio',
   variant_type: 'primary',
   account_sid: 'AC…',           // "AC" + 32 hex
@@ -231,29 +229,16 @@ create time:
 A misaligned pair (e.g. `intent: sms` + `tool_body_type: sftp`)
 returns a `422` with `body.tool_body_type` in `errors`.
 
-### `data_source_id` is required on every tool
+### `data_source_id` is optional but discriminator-aware
 
-Every tool names the data source it belongs to, whatever its intent
-or body type. A create without `data_source_id` is a `422` at
-`/data_source_id` (`can't be blank`); `update()` is a full
-replacement, so send it on every PUT too. The generated type still
-marks the field optional and nullable — the server's rule is the one
-that holds.
+When set, the tool is **embedded under a data source** — its
+lifecycle is tied to the parent data source, and ingestion paths
+expect it at that scope. When omitted, the tool is **standalone**
+on the datalake — available to any workflow that names it.
 
-What it drives:
-
-- **The messages a tool sends carry its data source's `uri`.** An
-  action status updater names one data source and matches polled
-  events to messages and action logs by that `uri` plus the vendor's
-  id (`action_status_updaters.md` §2). One data source may hold SMS,
-  MMS and voice tools; nothing checks what else is on it.
-- **A data source cannot be deleted while it still has tools.** The
-  delete answers `409` (`still has tools`); delete or move its tools
-  first. The foreign key restricts, so nothing cascades.
-
-The body type still signals the typical pattern: a `manual_upload`
-tool's data source IS the upload sink; a sender's data source is the
-one its messages, and its status updater, belong to.
+The body type itself signals the typical pattern: `manual_upload`
+is almost always embedded (the data source IS the upload sink);
+`sns`, `rest_api`, `sql_database` are typically standalone.
 
 ### Body-type sub-fields are validated against the matching discriminator branch (server-side)
 
@@ -377,7 +362,6 @@ const { data: sesTool } = await api.tools.create(tenantSlug, datalakeSlug, {
   intent: ToolIntent.EMAIL,
   status: 'active',
   datalake_id: datalakeId,
-  data_source_id: dataSourceId,
   body: {
     tool_body_type: 'email',
     provider: 'ses',
@@ -562,8 +546,8 @@ silent OIDC-provider outage can fail an otherwise-cosmetic
 
    scoping
      datalake_id          parent datalake (UUID)
-     data_source_id       required — the data source the tool belongs
-                          to (every intent; send it on every PUT)
+     data_source_id       (optional) parent data source for embedded
+                          tools; omit for standalone
 
    body (polymorphic — required keys depend on tool_body_type)
      tool_body_type       discriminator — names which branch shape
@@ -597,8 +581,8 @@ Capture both `id` and `slug` from the create response; never
 pre-compute either client-side. The **UUID `id`** is the CRUD path
 key (`.get` / `.update` / `.delete`) AND the cross-resource
 reference — workflows and data-activation clients bind a tool by
-`id` (`tool_id`), and action status updaters by `updater_tool_id`
-(see §7; an updater names a data source, not its sender tools). The `slug` is the human handle; it does
+`id` (`tool_id`), and action status updaters by `updater_tool_id` /
+`sender_tool_ids` (see §7). The `slug` is the human handle; it does
 NOT key a CRUD `.get` (passing it 422s `Expected :uuid`). See
 `type_naming.md` for the id/slug/name convention.
 
@@ -860,9 +844,9 @@ downstream resource that names a tool must apply AFTER it.
    `status: "error"` + non-empty `error_message`. If you see a
    5xx, file a platform bug, do not retry.
 
-5. **Tools list per datalake, not per data source**
+5. **Standalone vs embedded tool routing differs at list time**
    — `tools.list(tenant, datalake, query?)` returns ALL tools on
-   the datalake, across every data source. The Flop query
+   the datalake (standalone + embedded). The Flop query
    (type_naming.md) filters on `intent`, `status`, `name`, etc. —
    but `data_source_id` is NOT in the filterable set, so tools
    owned by a specific data source must still be filtered