fix(mothership): expose and validate tool attachment identities

Author: Sg312

apps/sim/lib/api/contracts/mothership-catalog.ts

@@ -4,6 +4,14 @@ import { v2BlockDetailSchema, v2BlockFieldSchema } from '@/lib/api/contracts/v2/
 /** Internal discovery adds compact catalog hints without changing the public v2 response. */
 const mothershipBlockFieldSchema = v2BlockFieldSchema.extend({
   valueSchema: z.record(z.string(), z.unknown()).optional(),
+  toolBinding: z
+    .object({
+      selectionMode: z.enum(['explicit', 'additive']),
+      discovery: z.array(z.string()),
+      naming: z.string(),
+      access: z.string(),
+    })
+    .optional(),
   optionsAvailability: z.string().optional(),
   options: z
     .array(

apps/sim/lib/mothership/agent-cli/curation.test.ts

@@ -95,6 +95,27 @@ describe('curateBlockDetail', () => {
     expect(await curateBlockDetail(input, viewer)).toBe(input)
   })
 
+  it.each(['agent', 'mothership'])(
+    'publishes the %s attachment contract on demand only',
+    async (id) => {
+      const original = { ...blockDetail(), id, inputSchema: [{ id: 'tools', type: 'tool-input' }] }
+      const result = await curateBlockDetail(ok(JSON.stringify(original)), viewer)
+      const detail = mothershipBlockDetailSchema.parse(JSON.parse(result.stdout))
+      const field = detail.inputSchema[0]
+      expect(field?.valueSchema).toMatchObject({
+        type: 'array',
+        items: { anyOf: expect.any(Array) },
+      })
+      expect(field?.toolBinding?.selectionMode).toBe(id === 'agent' ? 'explicit' : 'additive')
+      expect(field?.toolBinding?.naming).toContain(
+        id === 'agent' ? 'operations[operation].toolId' : 'call_integration_tool'
+      )
+      expect(v2BlockDetailSchema.parse(detail).inputSchema[0]).not.toHaveProperty('toolBinding')
+      expect(v2BlockDetailSchema.parse(detail).inputSchema[0]).not.toHaveProperty('valueSchema')
+      expect(original.inputSchema[0]).not.toHaveProperty('valueSchema')
+    }
+  )
+
   it.each(['start_trigger', 'api_trigger', 'input_trigger', 'human_in_the_loop'])(
     'publishes the input editor value contract for %s without changing v2',
     async (id) => {

apps/sim/lib/mothership/agent-cli/curation.ts

@@ -12,6 +12,7 @@ import { type V2BlockDetail, v2BlockDetailSchema } from '@/lib/api/contracts/v2/
 import { projectBlockOutputs } from '@/lib/catalog/projection/block-detail'
 import { resolveDeniedBlockOperations } from '@/lib/integrations/tool-projection'
 import { withModelHints } from '@/lib/mothership/agent-cli/model-hints'
+import { withToolBindingHints } from '@/lib/mothership/agent-cli/tool-binding-hints'
 import { agentCliFail } from '@/lib/mothership/agent-cli/types'
 import type { AgentCliRawResult } from '@/lib/mothership/generated/agent-cli'
 import { createToolAccessGate } from '@/lib/permission-groups/operation-access'
@@ -95,6 +96,7 @@ export async function curateBlockDetail(
         }
       : detail
   )
+  enriched = withToolBindingHints(enriched)
   if (detail.toolIds.includes('table_query_rows_v2')) {
     const workspace = await resolveActiveWorkspaceApplicationContext(viewer.workspaceId)
     enriched = {

apps/sim/lib/mothership/agent-cli/tool-binding-hints.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod'
+import type { MothershipBlockDetail } from '@/lib/api/contracts/mothership-catalog'
+import { getToolBindingAuthoringSchema } from '@/lib/workflows/tool-input/authoring'
+
+/** Publish only the selected block's attachment contract, not the integration tool catalog. */
+export function withToolBindingHints(detail: MothershipBlockDetail): MothershipBlockDetail {
+  const schema = getToolBindingAuthoringSchema(detail.id)
+  if (!schema) return detail
+  const { $schema: _version, ...valueSchema } = z.toJSONSchema(schema)
+  const isMothership = detail.id === 'mothership'
+  return {
+    ...detail,
+    inputSchema: detail.inputSchema.map((field) =>
+      field.type !== 'tool-input'
+        ? field
+        : {
+            ...field,
+            valueSchema,
+            toolBinding: {
+              selectionMode: isMothership ? 'additive' : 'explicit',
+              discovery: [
+                ...(!isMothership
+                  ? [
+                      'blocks get <type> --operation <operation>',
+                      'custom-tools list',
+                      'custom-tools get <id>',
+                    ]
+                  : []),
+                'mcp-servers list',
+                'mcp-servers tools list <serverId>',
+              ],
+              naming: isMothership
+                ? 'Use the exact MCP toolName returned by discovery. Sim Chat discovers the callable toolId and invokes it through call_integration_tool. An attachment title/name cannot rename the operation.'
+                : 'Integration operations use operations[operation].toolId from blocks get (not the UI toolName/title). Custom tools use custom_ followed by the saved definition title or inline title. MCP tools use a server-qualified ID derived from the discovered toolName. Duplicate bindings receive provider-generated suffixes. Do not override title, name, toolId or functionName when attaching a saved tool. Inline custom definitions require title = schema.function.name.',
+              access: isMothership
+                ? 'Selections add MCP operations to available integration access; this is not an integration allowlist. Empty tools does not disable integrations. Fixed MCP arguments, force mode and variable permission mode are not supported by this block. Actual calls remain subject to execution permissions and MCP policies.'
+                : 'This array defines the selected tools, subject to execution permissions. For integration, inline custom and individual MCP bindings, params fixes author-supplied values; remaining eligible parameters are model-supplied. Saved custom-tool references do not retain fixed arguments. auto lets the model choose, force requires a call, none disables the binding. Runtime helpers such as skill loading are separate. Labels do not enforce approvals or permissions.',
+            },
+          }
+    ),
+  }
+}

apps/sim/lib/workflows/application/apply-workflow-operations.test.ts

@@ -243,7 +243,7 @@ describe('applyWorkflowOperations', () => {
     })
 
     expect(mocks.normalizeState).toHaveBeenCalledWith(emptyGraph)
-    expect(mocks.applyOperations).toHaveBeenCalledWith(emptyGraph, operations, null)
+    expect(mocks.applyOperations).toHaveBeenCalledWith(emptyGraph, operations, null, false)
     expect(mocks.replace).toHaveBeenCalledTimes(1)
     expect(result.graph.blocks).toEqual(graphWithAddedBlock.blocks)
   })
@@ -539,7 +539,7 @@ describe('applyWorkflowOperations', () => {
       input: { workflowId: 'workflow-1', operations, baseGraph },
     })
     expect(mocks.loadNormalized).not.toHaveBeenCalled()
-    expect(mocks.applyOperations).toHaveBeenCalledWith(baseGraph, operations, null)
+    expect(mocks.applyOperations).toHaveBeenCalledWith(baseGraph, operations, null, true)
 
     vi.clearAllMocks()
     mocks.resolveContext.mockResolvedValue(context)
@@ -566,7 +566,7 @@ describe('applyWorkflowOperations', () => {
       input: { workflowId: 'workflow-1', operations, baseGraph },
     })
     expect(mocks.loadNormalized).toHaveBeenCalledWith('workflow-1')
-    expect(mocks.applyOperations).not.toHaveBeenCalledWith(baseGraph, operations, null)
+    expect(mocks.applyOperations).not.toHaveBeenCalledWith(baseGraph, operations, null, true)
   })
 
   it('applies the block enablement slice and declines a locked block as a skipped item', async () => {

apps/sim/lib/workflows/application/apply-workflow-operations.ts

@@ -305,7 +305,12 @@ export const applyWorkflowOperations = defineAuthorizedWorkflowUseCase({
       skippedItems,
       mintedBlockIds,
     } = await withBlockVisibility(blockVisibility, async () =>
-      applyOperationsToWorkflowState(baseGraph, filteredOperations, permissionConfig)
+      applyOperationsToWorkflowState(
+        baseGraph,
+        filteredOperations,
+        permissionConfig,
+        principal.kind === 'delegated' && principal.serviceId === 'copilot'
+      )
     )
     validationErrors.push(...credentialErrors)
 

apps/sim/lib/workflows/application/replace-workflow-state.test.ts

@@ -16,6 +16,7 @@ const mocks = vi.hoisted(() => ({
   assertIdsUnclaimed: vi.fn(),
   validate: vi.fn(),
   needsRedeployment: vi.fn(),
+  loadNormalized: vi.fn(),
 }))
 
 vi.mock('@sim/audit', () => ({
@@ -52,11 +53,15 @@ vi.mock('@/lib/workflows/sanitization/validation', () => ({
 vi.mock('@/lib/workflows/deployment-status', () => ({
   checkNeedsRedeployment: mocks.needsRedeployment,
 }))
+vi.mock('@/lib/workflows/persistence/utils', () => ({
+  loadWorkflowFromNormalizedTables: mocks.loadNormalized,
+}))
 
 import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { replaceWorkflowState } from '@/lib/workflows/application/replace-workflow-state'
 import { REFERENCES_UNCHECKED_NOTE } from '@/lib/workflows/editing/lint-report'
 import { validateInputsForBlock } from '@/lib/workflows/editing/validation'
+import { AgentBlock } from '@/blocks/blocks/agent'
 import { ExaBlock } from '@/blocks/blocks/exa'
 import { getBlock } from '@/blocks/registry'
 
@@ -93,7 +98,7 @@ describe('replaceWorkflowState', () => {
   beforeEach(() => {
     vi.clearAllMocks()
     vi.mocked(getBlock).mockImplementation((type) =>
-      type === 'exa' ? ExaBlock : defaultGetBlock?.(type)
+      type === 'exa' ? ExaBlock : type === 'agent' ? AgentBlock : defaultGetBlock?.(type)
     )
     mocks.resolveContext.mockResolvedValue(context)
     mocks.resolvePermission.mockResolvedValue('write')
@@ -110,6 +115,7 @@ describe('replaceWorkflowState', () => {
     })
     mocks.collectGraphIds.mockReturnValue({ blockIds: ['block-1'], edgeIds: [], subflowIds: [] })
     mocks.assertIdsUnclaimed.mockResolvedValue(undefined)
+    mocks.loadNormalized.mockResolvedValue({ blocks: {}, edges: [], loops: {}, parallels: {} })
   })
 
   /**
@@ -502,6 +508,71 @@ describe('replaceWorkflowState', () => {
     })
   })
 
+  describe('Mothership attachment identity on state replacement', () => {
+    const copilotPrincipal = {
+      kind: 'delegated' as const,
+      serviceId: 'copilot',
+      subjectUserId: 'user-1',
+      workspaceId: 'workspace-1',
+      delegationId: 'tool-call-1',
+      audience: 'sim:workflows',
+      issuedAt: new Date('2026-01-01T00:00:00Z'),
+      expiresAt: new Date('2099-01-01T00:00:00Z'),
+    }
+    const block = {
+      ...BLOCK,
+      type: 'agent',
+      subBlocks: {
+        tools: {
+          id: 'tools',
+          type: 'tool-input' as const,
+          value: [{ type: 'exa', operation: 'exa_search', title: 'Existing label' }],
+        },
+      },
+    }
+    const replacement = { ...input, blocks: { [BLOCK.id]: block } }
+
+    it.each([false, true])('rejects new aliases before persistence (dryRun=%s)', async (dryRun) => {
+      await expect(
+        replaceWorkflowState.execute({
+          principal: copilotPrincipal,
+          input: { ...replacement, dryRun },
+        })
+      ).rejects.toThrow('attachment names are read-only')
+      expect(mocks.replace).not.toHaveBeenCalled()
+      expect(mocks.notify).not.toHaveBeenCalled()
+    })
+
+    it('preserves an existing label when replacing the graph and editing other fields', async () => {
+      mocks.loadNormalized.mockResolvedValue({
+        blocks: { [BLOCK.id]: block },
+        edges: [],
+        loops: {},
+        parallels: {},
+      })
+      await expect(
+        replaceWorkflowState.execute({
+          principal: copilotPrincipal,
+          input: { ...replacement, blocks: { [BLOCK.id]: { ...block, name: 'Updated Agent' } } },
+        })
+      ).resolves.toMatchObject({ dryRun: false })
+      expect(mocks.replace).toHaveBeenCalledWith(
+        expect.objectContaining({
+          state: expect.objectContaining({
+            blocks: { [BLOCK.id]: { ...block, name: 'Updated Agent' } },
+          }),
+        })
+      )
+    })
+
+    it('leaves ordinary authoring unchanged and avoids loading the graph', async () => {
+      await expect(
+        replaceWorkflowState.execute({ principal: sessionPrincipal, input: replacement })
+      ).resolves.toMatchObject({ dryRun: false })
+      expect(mocks.loadNormalized).not.toHaveBeenCalled()
+    })
+  })
+
   /**
    * A replace stores blocks and their tool wiring wholesale, and the policies
    * deciding which of those a member may add take a human subject. A workspace

apps/sim/lib/workflows/application/replace-workflow-state.ts

@@ -27,7 +27,12 @@ import {
   collectWorkflowGraphIds,
   replaceWorkflowNormalizedState,
 } from '@/lib/workflows/persistence/replace-normalized-state'
+import { loadWorkflowFromNormalizedTables } from '@/lib/workflows/persistence/utils'
 import { validateWorkflowState } from '@/lib/workflows/sanitization/validation'
+import {
+  getToolBindingAuthoringSchema,
+  validateToolBindingAuthoring,
+} from '@/lib/workflows/tool-input/authoring'
 import { getBlock } from '@/blocks/registry'
 
 const logger = createLogger('ReplaceWorkflowState')
@@ -127,13 +132,36 @@ export const replaceWorkflowState = defineAuthorizedWorkflowUseCase({
 
     /** Use registry control types, never the caller's subblock type, just as operation edits do. */
     const blocks = structuredClone(sanitized.blocks) as Record<string, BlockState>
+    const enforceToolBindings =
+      principal.kind === 'delegated' &&
+      principal.serviceId === 'copilot' &&
+      Object.values(blocks).some((block) => getToolBindingAuthoringSchema(block.type))
+    const previous = enforceToolBindings
+      ? await loadWorkflowFromNormalizedTables(context.workflowId)
+      : undefined
+    if (enforceToolBindings && !previous) {
+      throw new OrchestrationError(
+        'validation',
+        'Cannot validate tool edits without the saved workflow state'
+      )
+    }
     for (const [blockId, block] of Object.entries(blocks)) {
       const config = getBlock(block.type)
       if (!config) continue
       const fields = new Map(config.subBlocks.map((field) => [field.id, field]))
       for (const [fieldId, stored] of Object.entries(block.subBlocks ?? {})) {
         const field = fields.get(fieldId)
         if (!field) continue
+        if (enforceToolBindings && field.type === 'tool-input') {
+          const savedBlock = previous?.blocks[blockId]
+          const error = validateToolBindingAuthoring(
+            block.type,
+            stored.value,
+            savedBlock?.type === block.type ? savedBlock.subBlocks[fieldId]?.value : undefined
+          )
+          if (error)
+            throw new OrchestrationError('validation', `Block ${block.name || blockId}: ${error}`)
+        }
         const result = validateValueForSubBlockType(
           field,
           stored.value,

apps/sim/lib/workflows/editing/builders.ts

@@ -158,14 +158,21 @@ export function createBlockFromParams(
   parentId?: string,
   errorsCollector?: ValidationError[],
   permissionConfig?: PermissionGroupConfig | null,
-  skippedItems?: SkippedItem[]
+  skippedItems?: SkippedItem[],
+  enforceToolBindingContract = false
 ): any {
   const blockConfig = getBlock(params.type)
 
   // Validate inputs against block configuration
   let validatedInputs: Record<string, any> | undefined
   if (params.inputs) {
-    const result = validateInputsForBlock(params.type, params.inputs, blockId)
+    const result = validateInputsForBlock(
+      params.type,
+      params.inputs,
+      blockId,
+      {},
+      enforceToolBindingContract
+    )
     validatedInputs = result.validInputs
     if (errorsCollector && result.errors.length > 0) {
       errorsCollector.push(...result.errors)

apps/sim/lib/workflows/editing/engine.ts

@@ -159,7 +159,8 @@ function orderOperations(operations: EditWorkflowOperation[]): EditWorkflowOpera
 export function applyOperationsToWorkflowState(
   workflowState: Record<string, unknown>,
   operations: EditWorkflowOperation[],
-  permissionConfig: PermissionGroupConfig | null = null
+  permissionConfig: PermissionGroupConfig | null = null,
+  enforceToolBindingContract = false
 ): ApplyOperationsResult {
   // Deep clone the workflow state to avoid mutations
   const modifiedState = structuredClone(workflowState)
@@ -186,6 +187,7 @@ export function applyOperationsToWorkflowState(
   })
 
   const ctx: OperationContext = {
+    enforceToolBindingContract,
     modifiedState,
     skippedItems,
     validationErrors,