improvement(whatsapp): validate + improve integration skill for file inputs/outputs (#5942)

* improvement(whatsapp): validate + improve integration skill for file inputs/outputs

* fix lint

* add whatsapp subblock migration

Author: icecrasher321

.agents/skills/add-block/SKILL.md

@@ -257,48 +257,94 @@ When your block accepts file uploads, use the basic/advanced mode pattern with `
 },
 ```
 
+**Keep the pair to one logical thing.** Basic is the file upload, advanced is *only* a reference to
+a file from a previous block. Gmail attachments are the reference implementation
+(`apps/sim/blocks/blocks/gmail.ts` — `attachmentFiles` / `attachments`).
+
+Do not overload the advanced side with alternate identifiers (a remote URL, a provider asset ID, a
+path). A subblock whose meaning changes based on what the string looks like is impossible to reason
+about, forces the params function to sniff the value, and makes the field's type meaningless. Give
+each alternative its own subblock outside the pair:
+
+```typescript
+// ✓ Good — the pair is "a file"; other sources are their own fields
+{ id: 'mediaFile',    type: 'file-upload', canonicalParamId: 'media', mode: 'basic' },
+{ id: 'mediaFileRef', type: 'short-input', canonicalParamId: 'media', mode: 'advanced' },
+{ id: 'mediaId',      type: 'short-input', mode: 'advanced' },  // separate concept
+{ id: 'mediaLink',    type: 'short-input', mode: 'advanced' },  // separate concept
+
+// ✗ Bad — one field meaning three things, resolved by guessing
+{ id: 'mediaRef', type: 'short-input', canonicalParamId: 'media', mode: 'advanced',
+  placeholder: 'File reference, media ID, or public URL' },
+```
+
+When several fields are mutually exclusive alternatives, mark them all `required: false` and enforce
+"exactly one" at execution — a conditionally-required canonical pair rejects the workflow before the
+other paths ever get a chance to supply the value.
+
 **Critical constraints:**
 - `canonicalParamId` must NOT match any subblock's `id` in the same block
-- Values are stored under subblock `id`, not `canonicalParamId`
+- A canonical group is **block-wide**, not per-operation: `buildCanonicalIndex` keys groups by
+  `canonicalParamId` across every subblock, and a group has exactly one `basicId`. Two operations
+  that each need a file pair need two distinct `canonicalParamId` values.
+- All members of a group must share the same `required` status
 
 ### Normalizing File Input in tools.config
 
-Use `normalizeFileInput` to handle all input variants:
+Put the normalization in `tools.config.params`, never in `tools.config.tool` — `tool` runs at
+serialization, before variable resolution, so a `<block.output>` file reference is not yet a value
+there.
 
 ```typescript
 import { normalizeFileInput } from '@/blocks/utils'
 
 tools: {
   access: ['service_upload'],
   config: {
-    tool: (params) => {
-      // Check all field IDs: uploadFile (basic), fileRef (advanced), fileContent (legacy)
-      const normalizedFile = normalizeFileInput(
-        params.uploadFile || params.fileRef || params.fileContent,
-        { single: true }
-      )
-      if (normalizedFile) {
-        params.file = normalizedFile
+    tool: (params) => `service_${params.operation}`,
+    params: (params) => {
+      // Read the CANONICAL id, not the subblock ids
+      const { file: fileParam, ...rest } = params
+      const file = normalizeFileInput(fileParam, { single: true })
+      return {
+        ...rest,
+        ...(file ? { file } : {}),
       }
-      return `service_${params.operation}`
     },
   },
 }
 ```
 
-**Why this pattern?**
-- Values come through as `params.uploadFile` or `params.fileRef` (the subblock IDs)
-- `canonicalParamId` only controls UI/schema mapping, not runtime values
-- `normalizeFileInput` handles JSON strings from advanced mode template resolution
+**Where the value actually lives at runtime.** The subblock `id` is where the UI *stores* the value,
+but it is not what the params function receives. `extractBlockParams`
+(`apps/sim/serializer/index.ts`) collapses each canonical group at serialization time:
+
+```typescript
+const sourceIds = [group.basicId, ...group.advancedIds].filter(Boolean)
+sourceIds.forEach((id) => delete params[id])   // subblock ids are deleted
+if (chosen !== undefined) params[group.canonicalId] = chosen
+```
+
+So by the time `tools.config.params(inputs)` runs (`executor/handlers/generic/generic-handler.ts`),
+`params.uploadFile` and `params.fileRef` are **gone** and the value is under `params.file`. Reading a
+subblock id there yields `undefined` and silently sends no file.
+
+Only the active mode's value survives — `getCanonicalValues` returns the basic value in basic mode
+and the first non-empty advanced value in advanced mode, so a stale value in the dormant mode can
+never leak. `normalizeFileInput` then handles the JSON string that advanced-mode template resolution
+produces.
+
+Note that `generic-handler` merges rather than replaces (`{ ...inputs, ...transformedParams }`), so
+omitting a key from the returned object does not strip it from what the tool receives. Tools simply
+ignore params they do not declare.
 
 ### File Input Types in `inputs`
 
-Use `type: 'json'` for file inputs:
+Declare the **canonical** id with `type: 'json'` — the subblock ids never reach `inputs`:
 
 ```typescript
 inputs: {
-  uploadFile: { type: 'json', description: 'Uploaded file (UserFile)' },
-  fileRef: { type: 'json', description: 'File reference from previous block' },
+  file: { type: 'json', description: 'File to upload (UserFile or reference)' },
   // Legacy field for backwards compatibility
   fileContent: { type: 'string', description: 'Legacy: base64 encoded content' },
 }

.agents/skills/add-integration/SKILL.md

@@ -213,7 +213,7 @@ export const {Service}Block: BlockConfig = {
 ```typescript
 // Basic: Visual selector
 {
-  id: 'channel',
+  id: 'channelSelector',
   type: 'channel-selector',
   mode: 'basic',
   canonicalParamId: 'channel',
@@ -228,10 +228,19 @@ export const {Service}Block: BlockConfig = {
 }
 ```
 
+Note neither subblock `id` is `channel` — the canonical id is a third name that both members map
+onto, and it is the only one that survives serialization.
+
 **Critical Canonical Param Rules:**
 - `canonicalParamId` must NOT match any subblock's `id` in the block
-- `canonicalParamId` must be unique per operation/condition context
-- Only use `canonicalParamId` to link basic/advanced alternatives for the same logical parameter
+- `canonicalParamId` must be unique **block-wide**, not per operation. `buildCanonicalIndex` keys
+  groups by `canonicalParamId` across all subblocks and a group holds exactly one `basicId`, so two
+  operations that each need their own pair must use two different canonical ids
+- Only use `canonicalParamId` to link basic/advanced alternatives for the same logical parameter.
+  A pair carries ONE concept — for files that means upload (basic) + file reference (advanced), as
+  in Gmail attachments (`blocks/blocks/gmail.ts`). Never overload the advanced side with alternate
+  identifiers like a URL or a provider asset ID; give those their own subblocks, mark all the
+  mutually exclusive sources `required: false`, and enforce "exactly one" at execution
 - `mode` only controls UI visibility, NOT serialization. Without `canonicalParamId`, both basic and advanced field values would be sent
 - Every subblock `id` must be unique within the block. Duplicate IDs cause conflicts even with different conditions
 - **Required consistency:** If one subblock in a canonical group has `required: true`, ALL subblocks in that group must have `required: true` (prevents bypassing validation by switching modes)

.claude/commands/add-block.md

@@ -256,48 +256,94 @@ When your block accepts file uploads, use the basic/advanced mode pattern with `
 },
 ```
 
+**Keep the pair to one logical thing.** Basic is the file upload, advanced is *only* a reference to
+a file from a previous block. Gmail attachments are the reference implementation
+(`apps/sim/blocks/blocks/gmail.ts` — `attachmentFiles` / `attachments`).
+
+Do not overload the advanced side with alternate identifiers (a remote URL, a provider asset ID, a
+path). A subblock whose meaning changes based on what the string looks like is impossible to reason
+about, forces the params function to sniff the value, and makes the field's type meaningless. Give
+each alternative its own subblock outside the pair:
+
+```typescript
+// ✓ Good — the pair is "a file"; other sources are their own fields
+{ id: 'mediaFile',    type: 'file-upload', canonicalParamId: 'media', mode: 'basic' },
+{ id: 'mediaFileRef', type: 'short-input', canonicalParamId: 'media', mode: 'advanced' },
+{ id: 'mediaId',      type: 'short-input', mode: 'advanced' },  // separate concept
+{ id: 'mediaLink',    type: 'short-input', mode: 'advanced' },  // separate concept
+
+// ✗ Bad — one field meaning three things, resolved by guessing
+{ id: 'mediaRef', type: 'short-input', canonicalParamId: 'media', mode: 'advanced',
+  placeholder: 'File reference, media ID, or public URL' },
+```
+
+When several fields are mutually exclusive alternatives, mark them all `required: false` and enforce
+"exactly one" at execution — a conditionally-required canonical pair rejects the workflow before the
+other paths ever get a chance to supply the value.
+
 **Critical constraints:**
 - `canonicalParamId` must NOT match any subblock's `id` in the same block
-- Values are stored under subblock `id`, not `canonicalParamId`
+- A canonical group is **block-wide**, not per-operation: `buildCanonicalIndex` keys groups by
+  `canonicalParamId` across every subblock, and a group has exactly one `basicId`. Two operations
+  that each need a file pair need two distinct `canonicalParamId` values.
+- All members of a group must share the same `required` status
 
 ### Normalizing File Input in tools.config
 
-Use `normalizeFileInput` to handle all input variants:
+Put the normalization in `tools.config.params`, never in `tools.config.tool` — `tool` runs at
+serialization, before variable resolution, so a `<block.output>` file reference is not yet a value
+there.
 
 ```typescript
 import { normalizeFileInput } from '@/blocks/utils'
 
 tools: {
   access: ['service_upload'],
   config: {
-    tool: (params) => {
-      // Check all field IDs: uploadFile (basic), fileRef (advanced), fileContent (legacy)
-      const normalizedFile = normalizeFileInput(
-        params.uploadFile || params.fileRef || params.fileContent,
-        { single: true }
-      )
-      if (normalizedFile) {
-        params.file = normalizedFile
+    tool: (params) => `service_${params.operation}`,
+    params: (params) => {
+      // Read the CANONICAL id, not the subblock ids
+      const { file: fileParam, ...rest } = params
+      const file = normalizeFileInput(fileParam, { single: true })
+      return {
+        ...rest,
+        ...(file ? { file } : {}),
       }
-      return `service_${params.operation}`
     },
   },
 }
 ```
 
-**Why this pattern?**
-- Values come through as `params.uploadFile` or `params.fileRef` (the subblock IDs)
-- `canonicalParamId` only controls UI/schema mapping, not runtime values
-- `normalizeFileInput` handles JSON strings from advanced mode template resolution
+**Where the value actually lives at runtime.** The subblock `id` is where the UI *stores* the value,
+but it is not what the params function receives. `extractBlockParams`
+(`apps/sim/serializer/index.ts`) collapses each canonical group at serialization time:
+
+```typescript
+const sourceIds = [group.basicId, ...group.advancedIds].filter(Boolean)
+sourceIds.forEach((id) => delete params[id])   // subblock ids are deleted
+if (chosen !== undefined) params[group.canonicalId] = chosen
+```
+
+So by the time `tools.config.params(inputs)` runs (`executor/handlers/generic/generic-handler.ts`),
+`params.uploadFile` and `params.fileRef` are **gone** and the value is under `params.file`. Reading a
+subblock id there yields `undefined` and silently sends no file.
+
+Only the active mode's value survives — `getCanonicalValues` returns the basic value in basic mode
+and the first non-empty advanced value in advanced mode, so a stale value in the dormant mode can
+never leak. `normalizeFileInput` then handles the JSON string that advanced-mode template resolution
+produces.
+
+Note that `generic-handler` merges rather than replaces (`{ ...inputs, ...transformedParams }`), so
+omitting a key from the returned object does not strip it from what the tool receives. Tools simply
+ignore params they do not declare.
 
 ### File Input Types in `inputs`
 
-Use `type: 'json'` for file inputs:
+Declare the **canonical** id with `type: 'json'` — the subblock ids never reach `inputs`:
 
 ```typescript
 inputs: {
-  uploadFile: { type: 'json', description: 'Uploaded file (UserFile)' },
-  fileRef: { type: 'json', description: 'File reference from previous block' },
+  file: { type: 'json', description: 'File to upload (UserFile or reference)' },
   // Legacy field for backwards compatibility
   fileContent: { type: 'string', description: 'Legacy: base64 encoded content' },
 }

.claude/commands/add-integration.md

@@ -212,7 +212,7 @@ export const {Service}Block: BlockConfig = {
 ```typescript
 // Basic: Visual selector
 {
-  id: 'channel',
+  id: 'channelSelector',
   type: 'channel-selector',
   mode: 'basic',
   canonicalParamId: 'channel',
@@ -227,10 +227,19 @@ export const {Service}Block: BlockConfig = {
 }
 ```
 
+Note neither subblock `id` is `channel` — the canonical id is a third name that both members map
+onto, and it is the only one that survives serialization.
+
 **Critical Canonical Param Rules:**
 - `canonicalParamId` must NOT match any subblock's `id` in the block
-- `canonicalParamId` must be unique per operation/condition context
-- Only use `canonicalParamId` to link basic/advanced alternatives for the same logical parameter
+- `canonicalParamId` must be unique **block-wide**, not per operation. `buildCanonicalIndex` keys
+  groups by `canonicalParamId` across all subblocks and a group holds exactly one `basicId`, so two
+  operations that each need their own pair must use two different canonical ids
+- Only use `canonicalParamId` to link basic/advanced alternatives for the same logical parameter.
+  A pair carries ONE concept — for files that means upload (basic) + file reference (advanced), as
+  in Gmail attachments (`blocks/blocks/gmail.ts`). Never overload the advanced side with alternate
+  identifiers like a URL or a provider asset ID; give those their own subblocks, mark all the
+  mutually exclusive sources `required: false`, and enforce "exactly one" at execution
 - `mode` only controls UI visibility, NOT serialization. Without `canonicalParamId`, both basic and advanced field values would be sent
 - Every subblock `id` must be unique within the block. Duplicate IDs cause conflicts even with different conditions
 - **Required consistency:** If one subblock in a canonical group has `required: true`, ALL subblocks in that group must have `required: true` (prevents bypassing validation by switching modes)

.claude/rules/sim-integrations.md

@@ -15,5 +15,6 @@ The full authoring instructions — tool/block/icon/trigger scaffolding, SubBloc
 
 - Tool IDs are `snake_case` (`service_action`). Register tools in `tools/registry.ts`, blocks in `blocks/registry-maps.ts` (the `BLOCK_REGISTRY` config map + `BLOCK_META_REGISTRY` catalog-meta map, alphabetically — `blocks/registry.ts` holds only the accessor functions), triggers in `triggers/registry.ts`.
 - Type coercions (`Number()`, etc.) belong in `tools.config.params` (runs at execution, after variable resolution) — never in `tools.config.tool` (runs at serialization; coercing there destroys dynamic `<Block.output>` references).
-- `canonicalParamId` must NOT match any subblock's `id`, must be unique per operation/condition context, and all subblocks in a canonical group must share the same `required` status. The `inputs` section and the params function reference canonical IDs, not raw subblock IDs.
+- `canonicalParamId` must NOT match any subblock's `id`, must be unique **block-wide** (groups are keyed by canonical id across every subblock and hold exactly one `basicId`, so two operations that each need a pair need two different canonical ids), and all subblocks in a canonical group must share the same `required` status. The `inputs` section and the params function reference canonical IDs, not raw subblock IDs — the serializer deletes the subblock IDs and republishes the active member's value under the canonical ID.
+- A canonical pair carries ONE concept. For files that is upload (basic) + file reference (advanced), as in Gmail attachments (`blocks/blocks/gmail.ts`). Never overload the advanced side with alternate identifiers (URL, provider asset ID) — give those their own subblocks, mark mutually exclusive sources `required: false`, and enforce "exactly one" at execution.
 - Blocks must also set the catalog/UI metadata fields `integrationType`, `tags`, `authMode`, `docsLink`, and export a `{Service}BlockMeta` — see the `/add-block` skill's BlockMeta section for details.